yjLa dZddlmZddlZddlZddlmZmZddlm Z m Z ddl m Z ddl mZehdZehd Zed Gd d ZdZdZed GddZed GddZed GddZd3dZd4dZGdd Zd5d"Zd6d#Zd7d&Zd8d(Zd9d)Zd:d.Z d;d/Z!d;d0Z"da"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_navigateT)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. Tboolwarnings_enabledFhard_stop_enabledintexact_failure_warn_afterexact_failure_block_aftersame_tool_failure_warn_aftersame_tool_failure_halt_afterno_progress_warn_afterno_progress_block_afterctSN)IDEMPOTENT_TOOL_NAMES;/home/ragecks/.hermes/hermes-agent/agent/tool_guardrails.pyz ToolCallGuardrailConfig.PsEZr?)default_factoryzfrozenset[str]idempotent_toolsctSr<)MUTATING_TOOL_NAMESr>r?r@rAz ToolCallGuardrailConfig.QsCVr?mutating_toolsctSr<) LoopCapConfigr>r?r@rAz ToolCallGuardrailConfig.Rs }r?'LoopCapConfig' loop_capsdataMapping[str, Any] | Nonereturn'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_failurer2same_tool_failurer6idempotent_no_progressr9r4r8r:rJ) r.r/r2r6r9r4r8r:rJ) isinstancerget_as_boolr.r/ _positive_intr2r6r9r4r8r:rH from_mapping)clsrKrPrQdefaultss r@rYz$ToolCallGuardrailConfig.from_mappingTs)$(( 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    r?N)rKrLrMrN)__name__ __module__ __qualname____doc__r.__annotations__r/r2r4r6r8r9r:rrCrFrJ classmethodrYr>r?r@r,r,?s7"!!!!#####$%%%%%%&&&&&() ))))() ))))"######$$$$$',u=Z=Z'['['[[[[[%*U;V;V%W%W%WNWWWW!&7N7N!O!O!OIOOOO) ) ) [) ) ) r?r,2cHeZdZUdZeZded<eZded<e d d Z d S) rHa'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). r1max_web_searches max_subagentsrKrLrMrIct|ts |S|}|t|d|jt|d|jS)zABuild config from the ``tool_loop_guardrails.loop_caps`` section.rdre)rdre)rUr_non_negative_intrVrdre)rZrKr[s r@rYzLoopCapConfig.from_mappings$(( 355L355s.+,,h.G,))8+A     r?N)rKrLrMrI) r\r]r^r_"_DEFAULT_MAX_WEB_SEARCHES_PER_TURNrdr`_DEFAULT_MAX_SUBAGENTS_PER_TURNrerarYr>r?r@rHrHsc ?>>>>8M8888    [    r?rHcHeZdZUdZded<ded<ed d Zdd Zd S)ToolCallSignaturezDStable, non-reversible identity for a tool name plus canonical args.str tool_name args_hashargsrLrM'ToolCallSignature'cXt|pi}||t|S)Nrmrn)canonical_tool_args_sha256)rZrmro canonicals r@ from_callzToolCallSignature.from_calls0' 33 sY')2D2DEEEEr?dict[str, str]c |j|jdS)z3Return public metadata without raw argument values.rrrrselfs r@ to_metadatazToolCallSignature.to_metadatas!^$.IIIr?N)rmrlrorLrMrp)rMrw)r\r]r^r_r`rarvr{r>r?r@rkrksjNNNNNNNNFFF[FJJJJJJr?rkceZdZUdZdZded<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.allowrlactioncodemessagermrr1countNzToolCallSignature | None signaturerMr-c|jdvS)N>warnr~rrys r@allows_executionz&ToolGuardrailDecision.allows_execution{///r?c|jdvS)N>haltblockrrys r@ should_haltz!ToolGuardrailDecision.should_haltrr?dict[str, Any]c|j|j|j|j|jd}|j|j|d<|S)N)rrrrmrr)rrrrmrrr{)rzrKs r@r{z!ToolGuardrailDecision.to_metadatasNkI|Z    > % $ : : < r?r@r}r}sBBFDGIENNNN*.I.... 000X0000X0      r?r}roMapping[str, Any]rMrlct|ts$tdt|jt j|dddtS)z5Return sorted compact JSON for parsed tool arguments.z!tool args must be a mapping, got FT,: ensure_ascii sort_keys separatorsdefault)rUr TypeErrortyper\jsondumpsrlros r@rsrss] dG $ $SQDJJy>>k>>>$!#   H#+D O   y ) ) $&**955F!-3* l4;#FFF4&;XyXX&2XXX#,*"+   H+3D'#O$yINNNNr?)failedrrr 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)rmrrridempotent_no_progress_warningz returned the same result z^ times. Use the result already provided or change the query instead of repeating it unchanged.)rrkrvrrrVrpoprrr/r8r}rr.r2r6_tool_failure_recovery_hintrrr9) rzrmrorrr_r same_countr result_hashpreviousrs r@ after_callz&ToolCallGuardrailController.after_call^sAD!!%// 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 Xabbbbr?r-c>||jjvrdS||jjvS)NF)rrFrC)rzrms r@rz*ToolCallGuardrailController._is_idempotents'  2 2 25DK888r?rrrkc |jj}|dkrM|j}|r2|j|kr't ddd|d||j|}||_|S|xjdz c_dS|d krf|j}|sdSt|}|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'loop_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.) rrJrdrr}rre_subagent_spawn_countr)rzrmrorcapscapr spawn_counts r@rz+ToolCallGuardrailController._check_loop_capsY{$  $ $'C t2c990".>#>>> (5'   '/#  ' '1 , ' '4  ' '$C t/55K(C//0",N4NNHKNNN (3'   '/#  % % 4 % %4tr?r<)rr)rMr)rMr)rmrlrorLrMr}) rmrlrorLrrrrrMr})rmrlrMr-)rmrlrorrrkrMr) r\r]r^r_rrrrrrrrr>r?r@rrsMM & & & &###X#5O5O5O5Oz# ZcZcZcZcZcZcx9999 <<<<<<r?rrcbtj|j|ddS)zCBuild a synthetic role=tool content string for a blocked tool call.)r guardrailF)r)rrrr{)rs r@toolguard_synthetic_resultrs? :%!--//      r?c |jdvs|js|S|jdkrdnd}d|d|jd|jd|jd }|pd |zS) z;Append runtime guidance to the current tool result content.>rrrzTool loop hard stopzTool loop warningz [z: z; count=z; rr)rrrr)rrlabelsuffixs r@append_toolguard_guidancer s...h6F. %-_%>%> ! !DWE H H H = H H"*. H H4<4D H H H  LbF ""r?rr1c2|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.r>)rmrcommons r@rrsa  N N% N N N J Y   _ r?rLc4t|tr|niSr<)rUrrs r@rr)sdG,, 444"4r?ct|pd}|? tj|dddt}n##t$rt|}YnwxYw|pd}t |S)NrFTrr)rrrrlrrt)rparsedrus r@rr-s V\r * *F  $ "% II $ $ $F III $Lb 9  s4AAvaluerrr-c ||St|tr|St|ttfrt|St|tr2|}|dvrdS|dvrdS|S)N>1onyestrueenabledT>0noofffalsedisabledF)rUr-r1floatrlstripr)rrlowereds r@rWrW?s }% %#u&&E{{%++--%%'' ; ; ;4 = = =5 Nr?cr||S t|}n#ttf$r|cYSwxYw|dkr|n|S)Nrr1r ValueErrorrrrs r@rXrXOsY }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.Nrrrs r@rgrgYs[ }U z "q[[66g-rct|tr|dnd}t|tr|rt |SdS)aUHow 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. tasksNr)rUrrVlistlen)rors r@rresS",D'!:!: DDHHW   E%55zz 1r?cvtj|ddS)Nzutf-8 surrogatepass)hashlibsha256encode hexdigest)rs r@rtrtss. >%,,w@@ A A K K M MMr?)rorrMrl)rmrlrrrMr)rr}rMrl)rrlrr}rMrl)rmrlrr1rMrl)rorLrMr)rrrMrl)rrrr-rMr-)rrrr1rMr1)rorrMr1)rrlrMrl)%r_ __future__rr r dataclassesrrtypingrrutilsr agent.tool_result_classificationr frozensetr=rEr,rhrirHrkr}rsrrrrrrrrWrXrgrrtr>r?r@rs!#""""" ((((((((!!!!!!HHHHHH" * i, $> > > > > > > > N&(""$ $! ! ! ! ! ! ! ! H $ J J J J J J J J  $>        FjjjjjjjjZ # # # #(5555$     .... . . . .     NNNNNNr?