sj |dZddlmZddlZddlZddlmZmZddlm Z m Z ddl m Z ddl mZehdZehd Zed d hZd Zd ZdZdZdd(Z Gd)d*Z!d?d,Z"d@d-Z#dAd0Z$dBd2Z%dCd3Z&dDd7Z'dEd8Z(dEd9Z)dFd:Z*dGd;Z+dS)Ha"Pure tool-call loop guardrail primitives. The controller in this module is intentionally side-effect free: it tracks per-turn tool-call observations and returns decisions. Runtime code owns whether those decisions become warning guidance, synthetic tool results, or controlled turn halts. ) annotationsN) dataclassfield)AnyMapping)safe_json_loads)file_mutation_result_landed> read_file web_search web_extract search_filessession_searchbrowser_consolebrowser_snapshotbrowser_get_imagesmcp_filesystem_read_filemcp_filesystem_search_filesmcp_filesystem_get_file_infomcp_filesystem_directory_treemcp_filesystem_list_directorymcp_filesystem_read_text_file"mcp_filesystem_read_multiple_files(mcp_filesystem_list_directory_with_sizes>todopatchmemorycronjobprocessterminal write_file browser_type execute_code send_message skill_manage browser_click browser_press delegate_taskbrowser_scrollbrowser_navigaterbfl_flux3_get_result) _get_result_pollix tool_namestrreturnboolcL|tvrdS|tS)z=Whether a tool is exempt from the identical-call loop notice.T)STALL_GUARD_REPEATABLE_TOOLSendswith _STALL_GUARD_REPEATABLE_SUFFIXES)r/s 9/home/agent/.hermes/hermes-agent/agent/tool_guardrails.pyis_stall_guard_repeatabler8fs(000t   > ? ??T)frozenceZdZUdZdZded<dZded<dZded <d Zded <d Z ded <dZ ded<dZ ded<d Z ded<e dZded<e dZded<e dZded<ed!dZd S)"ToolCallGuardrailConfigaThresholds for per-turn tool-call loop detection. Warnings are enabled by default and never prevent tool execution. Hard stops are explicit opt-in so interactive CLI/TUI sessions get a gentle nudge unless the user enables circuit-breaker behavior in config.yaml. Tr2warnings_enabledFhard_stop_enabledintexact_failure_warn_afterexact_failure_block_afterr-same_tool_failure_warn_aftersame_tool_failure_halt_afterno_progress_warn_afterno_progress_block_afterctSN)IDEMPOTENT_TOOL_NAMESr9r7z ToolCallGuardrailConfig.~sEZr9)default_factoryzfrozenset[str]idempotent_toolsctSrJ)MUTATING_TOOL_NAMESrLr9r7rMz ToolCallGuardrailConfig.sCVr9mutating_toolsctSrJ) LoopCapConfigrLr9r7rMz ToolCallGuardrailConfig.s }r9'LoopCapConfig' loop_capsdataMapping[str, Any] | Noner1'ToolCallGuardrailConfig'ct|ts |S|d}t|tsi}|d}t|tsi}|}|t|d|jt|d|jt |d|d|jt |d|d|jt |d |d |j t |d|d |j t |d|d |j t |d |d |j t|d S)zABuild config from the `tool_loop_guardrails` config.yaml section. warn_afterhard_stop_afterr=r> exact_failurerAsame_tool_failurerDidempotent_no_progressrGrCrFrHrV) r=r>rArDrGrCrFrHrV) isinstancerget_as_boolr=r> _positive_intrArDrGrCrFrHrT from_mapping)clsrWr[r\defaultss r7rdz$ToolCallGuardrailConfig.from_mappings)$(( 355LXXl++ *g.. J((#455/733 ! O355s%dhh/A&B&BHD]^^&txx0C'D'DhF`aa%29S0T0TUU1&&*72DHH=[4\4\]]5**$17BZ9[9[\\/$$'4##OTXX>Y5Z5Z[[2''*7##$7B`9a9abb5**%2##$a>abb0%%$00+1F1FGG7    r9N)rWrXr1rY)__name__ __module__ __qualname____doc__r=__annotations__r>rArCrDrFrGrHrrOrRrV classmethodrdrLr9r7r<r<ms7"!!!!#####$%%%%%%&&&&&() ))))() ))))"######$$$$$',u=Z=Z'['['[[[[[%*U;V;V%W%W%WNWWWW!&7N7N!O!O!OIOOOO) ) ) [) ) ) r9r<2cHeZdZUdZeZded<eZded<e d d Z d S) rTa'Per-turn caps on runaway-prone tool calls. Inspired by Claude Code v2.1.212 (Week 29, July 2026), which added caps on WebSearch calls and subagent spawns to stop runaway search / delegation loops. Here the caps count *within a single agent loop* (one turn): the counters reset in ``reset_for_turn`` at the start of every ``run_conversation``, so a legitimate multi-turn session is never starved, but a single turn that spirals into an unbounded search / delegation loop is stopped. Semantics differ from the per-turn loop *detector* above (which keys on repeated identical/failing calls): these caps are a hard ceiling on the total count of a tool within the turn and fire regardless of ``hard_stop_enabled``. A value of ``0`` disables the cap (unlimited). r@max_web_searches max_subagentsrWrXr1rUct|ts |S|}|t|d|jt|d|jS)zABuild config from the ``tool_loop_guardrails.loop_caps`` section.rorp)rorp)r`r_non_negative_intrarorp)rerWrfs r7rdzLoopCapConfig.from_mappings$(( 355L355s.+,,h.G,))8+A     r9N)rWrXr1rU) rgrhrirj"_DEFAULT_MAX_WEB_SEARCHES_PER_TURNrork_DEFAULT_MAX_SUBAGENTS_PER_TURNrprlrdrLr9r7rTrTsc ?>>>>8M8888    [    r9rTc0eZdZUdZdZded<dZded<dS)IdenticalCallObservationaOutcome of observing one completed tool call for the stall guards. ``notice`` is the identical-call loop-breaker notice (appended after the result). ``stub`` is the result-reference replacement for a byte-identical duplicate result (replaces the result content). Both may be set on the same call (3rd+ identical call): the stub replaces the payload and the notice is appended after it. N str | Nonenoticestub)rgrhrirjrxrkryrLr9r7rvrvs@FDr9rvcHeZdZUdZded<ded<ed d Zdd Zd S)ToolCallSignaturezDStable, non-reversible identity for a tool name plus canonical args.r0r/ args_hashargsrXr1'ToolCallSignature'cXt|pi}||t|S)Nr/r|)canonical_tool_args_sha256)rer/r} canonicals r7 from_callzToolCallSignature.from_calls0' 33 sY')2D2DEEEEr9dict[str, str]c |j|jdS)z3Return public metadata without raw argument values.rrselfs r7 to_metadatazToolCallSignature.to_metadatas!^$.IIIr9N)r/r0r}rXr1r~)r1r)rgrhrirjrkrlrrrLr9r7r{r{sjNNNNNNNNFFF[FJJJJJJr9r{ceZdZUdZdZded<dZded<dZded<dZded<d Z d ed <d Z d ed<e ddZ e ddZ ddZd S)ToolGuardrailDecisionz8Decision returned by the tool-call guardrail controller.allowr0actioncodemessager/rr@countNzToolCallSignature | None signaturer1r2c|jdvS)N>warnrrrs r7allows_executionz&ToolGuardrailDecision.allows_execution {///r9c|jdvS)N>haltblockrrs r7 should_haltz!ToolGuardrailDecision.should_halt rr9dict[str, Any]c|j|j|j|j|jd}|j|j|d<|S)N)rrrr/rr)rrrr/rrr)rrWs r7rz!ToolGuardrailDecision.to_metadatasNkI|Z    > % $ : : < rrrarCr_is_idempotentrrH) rr/r}r cap_block exact_countdecisionrecord _result_hash repeat_counts r7 before_callz'ToolCallGuardrailController.before_callxs%// <;M;MNN ((L4F4F RR   {, S(9 RRR R044YBB $+? ? ?,3>y>>k>>>$!#   H#+D O   y ) ) $&**955F!-3* l4;#FFF4&;XyXX&2XXX#,*"+   H+3D'#O$yINNNNr9)failedrrwr bool | Nonec t|}t||}|t||\}}|r4|j|ddz}||j|<|j|d|j|ddz}||j|<|j j r5||j j kr%tddd|d|d|||} | |_ | S|j jr+||j jkrtd d |d |d |||S|j jr3||j jkr#td d t#|||||St|||S|j|d|j|d||s,|j|dt||St'|} |j|} d} | | d| kr | ddz} | | f|j|<|j jr+| |j jkrtd d|d| d|| |St|| |S)Nrrsame_tool_failure_haltzStopped z : it failed z[ times this turn. Stop retrying the same failing tool path and choose a different approach.rrrepeated_exact_failure_warning has failed z times with identical arguments. This looks like a loop; inspect the error and change strategy instead of retrying it unchanged.same_tool_failure_warning)r/rrridempotent_no_progress_warningz returned the same result z^ times. Use the result already provided or change the query instead of repeating it unchanged.)rr{rrrrarpoprrr>rFrrr=rArD_tool_failure_recovery_hintrrrG) rr/r}rrr_r same_countr result_hashpreviousrs r7 after_callz&ToolCallGuardrailController.after_callsAD!!%// 4@@ >-i@@IFA / f488AFFJK4?D &y 1   ! !)T 2 2 27;;IqIIAMJ8BD *9 5{, t{?g1g1g0!1d9dd*ddd($'   '/#{+  t{?c0c0c,!9$<<+<<<(%'    {+  dk>f0f0f,!47 :NN'$' )9K[deee e "&&y$777 &**9d;;;""9-- S   ! !)T 2 2 2(9 RRR R"6** $((33  HQK;$>$>#A;?L(3\'B)$ ; ' LDK<^,^,^(5 ..L...$"#    %y Xabbbbr9r2c>||jjvrdS||jjvS)NF)rrRrO)rr/s r7rz*ToolCallGuardrailController._is_idempotent s'  2 2 25DK888r9c:||||jS)zTrack consecutive identical calls; return a loop-breaker notice or None. Back-compat wrapper around :meth:`observe_call` for callers that only care about the loop-breaker notice. ) observe_callrx)rr/r}rs r7observe_identical_callz2ToolCallGuardrailController.observe_identical_calls  D&99@@r9rF) tool_call_idrr'IdenticalCallObservation'ct|t}t|t |}|rt |nd}|r'|j|kr|j|kr|xjdz c_n&|r|nd|_||_|rdnd|_|pd|_ |j} d} t|sJ| tkr?| d| dzcxkrdkrnndnd d d d  | d zd} d| d|d} d} |r6| dkr0|s.t|tkr|||} t!| | S)u@Track consecutive identical calls; return notice + dedupe stub info. Two independent outputs from the same consecutive-streak tracker: - ``notice``: the compact loop-breaker notice, fired when the SAME tool is called with identical canonical arguments AND returns an identical result for the ``STALL_GUARD_IDENTICAL_CALL_THRESHOLD``-th (and every subsequent) consecutive time within the turn. Purely observational — never blocks the call. Allowlisted pollers (``is_stall_guard_repeatable``) are exempt from the NOTICE. - ``stub``: a short reference replacement for the CURRENT result, produced from the 2nd consecutive identical call whose fresh result is byte-identical to the previous one. The tool still executed — only the context representation is deduplicated, so polling semantics are preserved (a changed result flows through whole and resets the streak). Pollers are NOT exempt from stubbing: for a poller, an identical result means nothing changed, which is exactly when the stub saves the most context and loses nothing. Results under ``IDENTICAL_RESULT_STUB_MIN_CHARS`` and failed/error results are never stubbed, and only plain-string results are considered. Any intervening different call or changed result resets the streak. Callers substitute/append at tool RESULT construction time, which is cache-safe: tool results are append-only and never mutate already-sent context. rrNr d thstndrd)rr?r- z[hermes note: this is the z consecutive identical call to u with identical arguments returning the same result. Do not repeat it — change arguments, use a different tool, or proceed with what you have.]r?)rxry)r`r0r{rrrrrrrr8$STALL_GUARD_IDENTICAL_CALL_THRESHOLDralenIDENTICAL_RESULT_STUB_MIN_CHARS_build_result_reference_stubrv) rr/r}rrr is_plain_strrrrrxordinalrys r7rz(ToolCallGuardrailController.observe_callsF"&#.. %// <;M;MNN .:Bl6***   F*i772kAA  ( (A - ( ( (7C)LD &1>>44YEED'vDAAAAr9 file_pathc*|r|r||j|<dSdSdS)a Remember the spillover path a persisted result was saved to. When the first occurrence of a result entered context as a persisted-output preview, a later reference stub must carry the spillover file path so the reference can't dangle. N)r)rrrs r7record_persisted_resultz3ToolCallGuardrailController.record_persisted_resultls@  CI C9BD ( 6 6 6 C C C Cr9cF tt|}n#t$rd}YnwxYwt|tkr|dtdz}|j}|rd|dnd}d|d|d |d }|r|j|nd}|r |d |d z }|S) a/Build the reference stub replacing a byte-identical duplicate result. Carries the tool name + a canonical-args preview so that even if context compression later evicts the referenced result, the model still knows WHAT the call was (cheap dangling-reference mitigation). z{}Nu…z (tool_call_id )rz3[hermes note: this result is byte-identical to the z result earlier this turnz2. Refer to that result; it has not changed. Args: rz* [The referenced result was persisted to: uB — page through it with read_file if you need the full content.])rrrr_RESULT_STUB_ARGS_PREVIEW_CHARSrrra)rr/r} args_previewfirst_idrefry spill_paths r7rz8ToolCallGuardrailController._build_result_reference_stubvs .|D/A/ABBLL   LLL |  > > >'(H)H(HIEQL7/7?+++++R .) . .'* . .* . . . DLUT155h???QU   PjPPP D s  ..rrr{c |jj}|dkrM|j}|r2|j|kr't ddd|d||j|}||_|S|xjdz c_dS|d krn|j}|sdSt|}|d krdS|j|kr/t dd d |jd |d||j|}||_|S|xj|z c_dSdS)aNEnforce and advance the per-turn runaway-loop counters. Returns a ``block`` decision when the cap is already reached, otherwise increments the relevant counter for the allowed call and returns ``None``. A cap of 0 disables that limit entirely. Counters reset each turn via ``reset_for_turn``. r rloop_web_search_capz/Blocked web_search: this turn has already made z web searches, the per-turn limit. This looks like a runaway search loop. Work with the results you already have and give the user your answer.rrNr'rloop_subagent_capz5Blocked delegate_task: this turn has already spawned z subagents (limit zl). This looks like a runaway delegation loop. Finish the work with the results you have and answer the user.) rrVrorrrrp_subagent_spawn_countr)rr/r}rcapscapr spawn_counts r7rz+ToolCallGuardrailController._check_loop_capsk{$  $ $'C t2c990".>#>>> (5'   '/#  ' '1 , ' '4  ' '$C t/55Kat(C//0",N4NNHKNNN (3'   '/#  % % 4 % %4tr9rJ)rr)r1r)r1r)r/r0r}rXr1r) r/r0r}rXrrwrrr1rr/r0r1r2)r/r0r}rXrrwr1rw) r/r0r}rXrrwrr0rr2r1r)rr0rr0r1r)r/r0r}rXr1r0)r/r0r}rrr{r1r)rgrhrirjrrrrrrrrrrrrrLr9r7rrNsUMM&&&&>###X#5O5O5O5Oz# ZcZcZcZcZcZcx9999 A A A A&MBMBMBMBMBMB^CCCCrrrzTool loop hard stopzTool loop warningz [z: z; count=z; rr)rrrr)rrlabelsuffixs r7append_toolguard_guidancers...h6F. %-_%>%> ! !DWE H H H = H H"*. H H4<4D H H H  LbF ""r9rr@c2|d|d}|dkr|dzS|dzS)zDAction-oriented guidance for recovering from repeated tool failures.rz times this turn. This looks like a loop. Do not switch to text-only replies; keep using tools, but diagnose before retrying. First inspect the latest error/output and verify your assumptions. rzFor terminal failures, run a small diagnostic such as `pwd && ls -la` in the same tool, then try an absolute path, a simpler command, a different working directory, or a different tool such as read_file/write_file/patch.zTry different arguments, a narrower query/path, an absolute path when relevant, or a different tool that can make progress. If the blocker is external, report the blocker after one diagnostic attempt instead of repeating the same failing path.rL)r/rcommons r7rrsa  N N% N N N J Y   _ r9rXc4t|tr|niSrJ)r`rrs r7rrsdG,, 444"4r9ct|pd}|? tj|dddt}n##t$rt|}YnwxYw|pd}t |S)NrFTrr)rrrr0rr)rparsedrs r7rrs V\r * *F  $ "% II $ $ $F III $Lb 9  s4AAvaluerrc ||St|tr|St|ttfrt|St|tr2|}|dvrdS|dvrdS|S)N>1onyestrueenabledT>0noofffalsedisabledF)r`r2r@floatr0stripr)r#rlowereds r7rbrbs }% %#u&&E{{%++--%%'' ; ; ;4 = = =5 Nr9cr||S t|}n#ttf$r|cYSwxYw|dkr|n|S)Nrr@r ValueErrorr#rr"s r7rcrc)sY }U z "q[[66g- ,,cr||S t|}n#ttf$r|cYSwxYw|dkr|n|S)ziParse a session-cap value. 0 is a valid (disable) value; negatives and junk fall back to the default.Nrr3r5s r7rrrr3s[ }U z "q[[66g-r6cpt|trNt|dpd}|dvrdSt|tr|dnd}t|t r|rt|SdS)aHow many subagents a single delegate_task call spawns. delegate_task runs in one of two modes: a batch (``tasks`` is a non-empty list, one child per item) or a single task (``goal``). Count the batch size when present, otherwise 1, so the session subagent cap reflects real spawns rather than delegate_task invocations. Control actions (list/steer/stop) spawn nothing and must not consume the cap. rr)liststeerstoprtasksNr)r`rr0rar0rr9r)r}rr<s r7rr?s$  TXXh''-2..4466<<>> . . .1!+D'!:!: DDHHW   E%55zz 1r9cvtj|ddS)Nzutf-8 surrogatepass)hashlibsha256encode hexdigest)r#s r7rrRs. >%,,w@@ A A K K M MMr9r)r}rr1r0)r/r0rrwr1r)rrr1r0)rr0rrr1r0)r/r0rr@r1r0)r}rXr1r)rrwr1r0)r#rrr2r1r2)r#rrr@r1r@)r}rr1r@)r#r0r1r0),rj __future__rr?r dataclassesrrtypingrrutilsr agent.tool_result_classificationr frozensetrKrQr4r6rrr r8r<rsrtrTrvr{rrrrrrrrrrbrcrrrrrLr9r7rIs#""""" ((((((((!!!!!!HHHHHH" * i6 )y  $ ()$#& #&@@@@ $> > > > > > > > N&(""$ $! ! ! ! ! ! ! ! H $         $ J J J J J J J J  $>        FGGGGGGGGT  # # # #(5555$     .... . . . .    &NNNNNNr9