`gjKldZddlmZddlZddlZddlZddlZddlZddlm Z ddl m Z m Z m Z mZddlmZej"eZdZdZeefZd Zdd Zd d Zd!d Z d"d Zd#dZd$dZd%dZd&dZd'dZ d(dZ!GddZ"ddd d)dZ#d(dZ$d*dZ%ddddd d+dZ&d,dZ'd-dZ(y).u}Write-approval gate + pending store for memory and skill writes. Background ---------- The agent writes to two persistent stores that survive across sessions: * **memory** — MEMORY.md / USER.md, small (~200 char) declarative entries * **skills** — SKILL.md + supporting files, potentially huge (10-100 KB) Both stores are written from two origins: * **foreground** — a normal agent turn (user is present / chatting) * **background_review** — the self-improvement review fork that runs after a turn and autonomously decides what to save (the source of the "wrong assumptions" users complained about) This module lets the user gate those writes per-subsystem with a boolean ``write_approval``: * ``false`` (default) — write freely (the pre-gate behaviour) * ``true`` — require approval: do not commit the write; either prompt inline (memory, interactive CLI only) or **stage** it to a pending store and surface it for the user to approve or reject out-of-band The size asymmetry between memory and skills is real and unavoidable: a memory entry can be reviewed inline in a chat bubble; a 100 KB SKILL.md cannot. So the gate stages BOTH to disk, but review affordances differ by subsystem (see ``hermes_cli`` slash handlers): memory shows full content, skills show metadata + a one-line gist + a ``diff`` escape hatch (CLI/dashboard/file). Staging is mandatory for background-origin writes (a daemon thread cannot block on an interactive prompt) and for gateway sessions (no inline prompt channel — review happens via ``/memory pending``). Foreground CLI memory writes prompt inline via the dangerous-command approval callback; skill writes always stage (too big to eyeball mid-loop). Pending records live under ``/pending/{memory,skills}/.json`` so they survive process restarts and can be reviewed from CLI, gateway, or the web dashboard. ) annotationsN)Path)AnyDictListOptionalget_hermes_homememoryskillswrite_approvalc|tvry ddlm}m}|}|||td}t |S#t $rYywxYw)u'Return whether the approval gate is enabled for ``subsystem``. Reads ``.write_approval`` from config.yaml. Defaults to ``False`` (gate off — writes flow freely) for any unset / invalid value so existing installs keep their current behaviour until the user opts in. Fr) load_configcfg_get)default) _SUBSYSTEMShermes_cli.configrr CONFIG_KEY Exception_normalize_enabled) subsystemrrcfgraws G/root/.hermes/venv/lib/python3.12/site-packages/tools/write_approval.pywrite_approval_enabledrJsO #:mc9j%@ c "" s5 AAct|tr|St|tr |jj dvSy)aCoerce a config value to a bool. Default (unknown) is False (gate off). Accepts real bools and the usual truthy/falsey strings. YAML 1.1 parses bare ``on``/``off``/``yes``/``no`` as bools already, so the string branch is mostly for hand-edited configs. >1onyestrueapproveenabledF) isinstanceboolstrstriplower)values rrr\s;% %{{}""$(XXX c"tdz |z S)Npendingr )rs r _pending_dirr,ns  y (9 44r)ctjjdd}|||jdd|xsdj |xsdt j |d} t |}|jdd||d z }|jd }|jtj|d d dtj|||S#t$r$} tj!d|| dYd} ~ |Sd} ~ wwxYw)uOPersist a pending write and return a short record describing it. Args: subsystem: ``memory`` or ``skills``. payload: the exact kwargs needed to replay the write when approved (e.g. ``{"action": "add", "target": "user", "content": "..."}`` for memory, or the full ``skill_manage`` kwargs for skills). summary: a one-line human-readable description shown in pending lists. For skills this is the LLM/heuristic gist; for memory it can be the entry text itself. origin: ``foreground`` or ``background_review`` — recorded for audit. Returns a dict with ``id`` and metadata. Best-effort: on disk failure it logs and still returns a record (the write is simply lost, which is the safe failure for an approval gate — nothing is silently committed). Naction foreground)idrr/summaryorigin created_atpayloadT)parentsexist_ok.jsonz .json.tmpF) ensure_asciiindentutf-8encodingz$Failed to stage pending %s write: %s)exc_info)uuiduuid4hexgetr&timer,mkdir with_suffix write_textjsondumpsosreplacerloggererror) rr6r3r4pidrecorddpathtmpes r stage_writerUrs$ **,  2A C++h+Mr((*(LiikFZ  # t,cU%= {+ tzz&uQGRYZ 3 M Z ;YTX YY MZs%A6C D &DD cJt|}|jsgSg}|jdD]7} |jt j |j d9|jd|S#t$rtjd|YpwxYw)z;Return all pending records for ``subsystem``, oldest first.*.jsonr=r>z&Skipping unreadable pending record: %sc&|jddS)Nr5r)rD)rs rzlist_pending..squu\15r))key) r,existsglobappendrIloads read_textrrMwarningsort)rrQrecordsps r list_pendingresYA 88: $&G VVH H H NN4::akk7k&CD EH  LL5L6 N H NNCQ G Hs4BB"!B"ct||dz }|jsy tj|j dS#t $rYywxYw)z.Return a single pending record by id, or None.r9Nr=r>)r,r\rIr_r`r)r pending_idrRs r get_pendingrhsU  " |5%9 9D ;;=zz$..'.:;; s$A AAct||dz } |jr|jy y#t$r"}tj d|||Yd}~yd}~wwxYw)z4Delete a pending record. Returns True if it existed.r9Tz#Failed to discard pending %s/%s: %sNF)r,r\unlinkrrMrN)rrgrRrTs rdiscard_pendingrksk  " |5%9 9DV ;;= KKM   V :IzSTUU Vs 6 A!AA!ct|}|jsy td|jdDS#t$rYywxYw)z9Cheap count of pending records (for notification badges).rc3 K|]}dyw)N).0_s r z pending_count..s/1/s rW)r,r\sumr]r)rrQs r pending_countrtsIYA 88:/affX./// s ? A  A c< ddlm}|S#t$rYywxYw)a=Return the active write origin: ``foreground`` or ``background_review``. Reuses the skill-provenance ContextVar, which the background review fork already sets (see ``agent.background_review`` / ``AIAgent._spawn_background_review``). Foreground agent turns leave it at the default ``foreground``. rget_current_write_originr1)tools.skill_provenancerwrrvs rcurrent_originrys%C')) s  ctdk(S)Nbackground_review)ryror)r is_backgroundr|s  2 22r)c&eZdZdZdZddddddZy) GateDecisionuResult of evaluating the write gate for a single write attempt. Exactly one of the boolean flags is True: * ``allow`` — proceed with the real write (gate off, or an inline approval was granted). * ``blocked`` — refuse the write (the user denied an inline approval prompt). ``message`` explains why; surface it to the agent. * ``stage`` — do not write; the caller should stage the payload via ``stage_write`` (gate on, and no inline prompt is available — gateway, background review, script, or any skill write). ``message`` is the user-facing "staged for approval" note. allowblockedstagemessageFr0c<||_||_||_||_y)Nr)selfrrrrs r__init__zGateDecision.__init__s    r)N)__name__ __module__ __qualname____doc__ __slots__rror)rr~r~s 9I %uE2r)r~r0)inline_summary inline_detailc$t|s tdSt}|tk(s|r!|tk(rdnd}tdd|d|dSt r-t ||}|dur tdS|d ur tdd Stdd S) uDecide what to do with a pending write for ``subsystem``. Args: subsystem: ``memory`` or ``skills``. inline_summary: short description used as the inline approval prompt header (memory foreground path only). inline_detail: full content shown in the inline prompt (memory entries are small; skills never take the inline path). Decision matrix: gate off (default) → allow (writes flow freely) gate on, memory + interactive CLI → inline approve/deny prompt gate on, memory + gateway/script/bg → stage gate on, skills (any origin) → stage (too big to review inline) Note: there is no config-driven "blocked" outcome — the gate only ever delays a write for approval, never silently refuses it. ``blocked`` is still produced when the user *actively denies* an inline prompt. T)rz/skills pendingz/memory pendingzStaged for approval (u6.write_approval is on). Not yet saved — review with .)rrFz6Memory write denied by user. The change was not saved.)rruaStaged for approval (memory.write_approval is on). Not yet saved — review with /memory pending.)rr~r|SKILLS_interactive_approval_available_prompt_inline_memory_approval)rrr backgroundwheregranteds r evaluate_gaters* ") ,$''JFj%.&%8!>O' {3116q:  '(0O d?d+ + e P   = r)c@ ddlm}|duS#t$rYywxYw)uTrue when a foreground memory write can be approved inline. Inline prompting requires a per-thread approval callback registered by the interactive CLI (``tools.terminal_tool.set_approval_callback``). Every other surface stages instead: * **Gateway/API sessions** — the dangerous-command ``/approve`` round-trip lives in the pending-approval queue (``submit_pending`` + ``_await_gateway_decision``), which ``prompt_dangerous_approval`` never reaches; trying to prompt from a gateway session would hit the ``input()`` fallback and silently deny. Staging gives the user a real review affordance (``/memory pending``) instead. * Scripts, cron, and background threads — no user present. r_get_approval_callbackNF)tools.terminal_toolrrrs rrr;s*>%'t33 s  c( ddlm}|}|y|jxsd}|j}d|}|r|n|} |||d}|d vry |d k(ryy#t$rYywxYw#t$r } tj d| Yd} ~ yd} ~ wwxYw) uoPrompt the user inline to approve a memory write. Returns True (approved), False (denied), or None (no interactive prompt available / prompt failed → caller should stage instead). Reuses the per-thread CLI approval callback registered for dangerous commands (``tools.terminal_tool.set_approval_callback``). The callback is invoked directly — NOT via ``prompt_dangerous_approval`` — because that wrapper falls back to ``input()`` (deadlock-prone under prompt_toolkit, see #15216) and converts callback errors into a silent deny; here a failed prompt must stage the write instead. rrNzSave to memory?zSave to memory: F)allow_permanentz(Inline memory approval prompt failed: %s>oncesessionTdeny)rrrr&rMrN) r3detailrcallbackheaderbody descriptioncommandchoicerTs rrrQs>&'H ]]_ 1 1F <<>D$VH-KdG ';F $$  ; &  ?Cs)A A( A%$A%( B1B  B)content file_path old_string new_stringc |dvra|r_t|}t|dk\rt|dzdzdn t|d}|dk(rdnd}|r|d|d |d |d S|d|d |d S|d k(rE|xsd} |r|jddznd} |r|jddznd} d|d| d| d| d S|dk(r d|d|dS|dk(r d|d|dS|dk(rd|dS|d|dS)ugBuild a one-line human gist for a pending skill write. Heuristic, no model call — the gist surfaces enough to decide approve/reject in a chat bubble, while the full diff stays behind /skills diff (CLI/ dashboard/file). For create/edit it pulls the frontmatter ``description:``; for patch/write_file it describes the size of the change. >editcreateirnz KBz charsrrewritez 'u' — z ()z' (patchSKILL.md rzpatch 'z' z (+z/-z lines) write_filezwrite z in '' remove_filezremove z from 'deletedelete skill ')_frontmatter_descriptionlencount) r/namerrrrdescsizeverbtargetremovedaddeds r skill_gistrsb##'036w<43G#g,$&*+3/PST[P\~]cMd!X-x9 V2dV6$r$q9 9r$s4&** (j0:*""4(1,.8   &*abE7"WIWEE  {%vQ//  74&22 vQ''XRvQ r)cddl}|jd||j}|sy|jdj j d}|ddS)zBExtract the ``description:`` value from SKILL.md YAML frontmatter.rNz^description:\s*(.+)$r0rnz'")research MULTILINEgroupr&)rrmrs rrrsO  *GR\\BA  771:    # #E *D :r)cddl}|jdi}|jdd}|jdd}|dk(r|jdxsdS dd lm}d}d }|c||}|rY|d } |d k(r| d z } n&|d vr|jdxsd } | | z } | }n| d z } | j r| j d}|d k(r|jdxsd} n|dk(rH|jdxsd} |jdxsd}|r|j| |nd| d|d} nL|dk(r|jdxsd} n1|dk(rd|jdd|dS|dk(rd|dSd|d |d!S|j|jd"#| jd"#d$|d%|&}dj|}|xsd'S#t$rd}Y}wxYw#t$rd}Y&wxYw)(aFBuild a full unified diff (or full content) for a staged skill write. Used by /skills diff on a surface that can render it (CLI pager, web dashboard, or by opening the pending JSON file). For create this is the new file content; for edit/patch it is a unified diff against the current on-disk skill. rNr6r/r0rrr) _find_skillrrRr>rrrr=r>rrrz(patch u → rr file_contentrz remove file: z from skill 'rrr(z on 'z')T)keependsza/zb/)fromfiletofilez(no textual change)) difflibrDtools.skill_manager_toolrrr\r`rL unified_diff splitlinesjoin)rPrr6r/rrcurrent target_labelfoundbaserdrelnewold_snew_sdifftexts rskill_pending_diffrsUjjB'G [[2 &F ;;vr "D  I&,"-8GLD! =D:%22kk+.<*3J" :% 88:kk7k;Gkk)$* 7  L)/R L)/R/6gooeU+geYeTYS\\]<^ < kk.)/R = w{{;78 dV1MM 8 vQ''6(%vR((   D) %l^$L>"  D 774=D  ((([  (  s$G #"G GG G,+G,)rr%returnr$)r(rrr$)rr%rr) rr%r6Dict[str, Any]r3r%r4r%rr)rr%rzList[Dict[str, Any]])rr%rgr%rzOptional[Dict[str, Any]])rr%rgr%rr$)rr%rint)rr%)rr$)rr%rr%rr%rr~)r3r%rr%rzOptional[bool])r/r%rr%rr%rr%rr%rr%rr%)rr%rr%)rPrrr%))r __future__rrIloggingrKrErApathlibrtypingrrrrhermes_constantsr getLoggerrrMMEMORYrrrrrr,rUrerhrkrtryr|r~rrrrrrror)rrs'R#  ,,,   8 $  v  #$ $5%%),%1?%P   3.<>');!$;.:;|,,f:< "b!#  03  (+ >@)r)