tool_guardrails.py 35 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672
  1. """Pure tool-call loop guardrail primitives.
  2. The controller is side-effect free: it tracks per-turn tool-call observations
  3. and returns decisions. Runtime code decides whether a decision becomes warning
  4. guidance, a synthetic tool result, or a controlled turn halt.
  5. """
  6. from __future__ import annotations
  7. import hashlib
  8. import json
  9. from collections import deque
  10. from dataclasses import asdict, dataclass, field, fields
  11. from typing import Any, Mapping
  12. from utils import safe_json_loads
  13. from agent.tool_result_classification import (
  14. shape_failure_error, file_mutation_result_landed, has_failure_marker, is_guardrail_refusal, is_rate_limited)
  15. IDEMPOTENT_TOOL_NAMES = frozenset({
  16. "read_file", "search_files", "web_search", "web_extract", "session_search", "skill_view", "skills_list",
  17. "browser_snapshot", "browser_console", "browser_get_images", "mcp_filesystem_read_file",
  18. "mcp_filesystem_read_text_file", "mcp_filesystem_read_multiple_files", "mcp_filesystem_list_directory",
  19. "mcp_filesystem_list_directory_with_sizes", "mcp_filesystem_directory_tree", "mcp_filesystem_get_file_info",
  20. "mcp_filesystem_search_files",
  21. })
  22. MUTATING_TOOL_NAMES = frozenset({
  23. "terminal", "execute_code", "write_file", "patch", "todo_list", "memory", "skill_manage",
  24. "browser_click", "browser_type", "browser_press", "browser_scroll", "browser_navigate",
  25. "send_message", "cronjob_manage", "delegate_task", "process_manage",
  26. })
  27. # Pollers: legitimately re-invoked with identical args; the identical-call NOTICE never fires.
  28. STALL_GUARD_REPEATABLE_TOOLS = frozenset({"process_manage"})
  29. _STALL_GUARD_REPEATABLE_SUFFIXES = ("_get_result", "_poll") # generated / MCP poller conventions
  30. # Nth consecutive identical (tool, args, result) call that fires the notice; 3 tolerates one double-check.
  31. STALL_GUARD_IDENTICAL_CALL_THRESHOLD = 3
  32. # Repeating multi-call cycles (A,B,A,B,... with identical args AND results) defeat the
  33. # consecutive streak above — every alternation resets it, so a model replaying the same
  34. # 2–4 call batch each iteration ran to the budget unflagged (port of can1357/oh-my-pi#10521,
  35. # which widened their loop guard from single-call turns to whole tool-call batches).
  36. # Longest cycle period detected; laps reuse the streak thresholds (notice at
  37. # STALL_GUARD_IDENTICAL_CALL_THRESHOLD laps, halt at no_progress_block_after laps).
  38. _STALL_GUARD_MAX_CYCLE_PERIOD = 4
  39. # History window: enough for block_after laps of the longest cycle plus slack.
  40. _STALL_GUARD_CYCLE_HISTORY = 64
  41. # From the 2nd byte-identical repeat the duplicate payload becomes a reference stub; smaller results
  42. # aren't worth it, errors never are. The args preview keeps WHAT was called if compression evicts the original.
  43. IDENTICAL_RESULT_STUB_MIN_CHARS = 512
  44. _RESULT_STUB_ARGS_PREVIEW_CHARS = 120
  45. # Tools whose "failure" is normal work output (red test run, empty grep, page timeout).
  46. # same_tool_failure (DIFFERENT commands) never halts these; only an exact-args replay with
  47. # no intervening change, or an identical-result streak, can.
  48. FAILURE_TOLERANT_TOOL_NAMES = frozenset({
  49. "terminal", "execute_code", "process_manage", "process", "browser_navigate", "web_extract",
  50. })
  51. # A successful call to one of these marks progress for every failing signature still counted
  52. # this turn: the next retry is a new experiment (edit -> re-run), not a replay.
  53. PROGRESS_RESET_TOOL_NAMES = frozenset({
  54. "write_file", "patch", "terminal", "execute_code", "browser_click", "browser_type", "browser_press",
  55. "browser_navigate", "process_manage", "process", "delegate_task", "send_message", "cronjob",
  56. "cronjob_manage", "todo", "todo_list", "memory", "skill_manage",
  57. })
  58. _BOOL_FIELDS = ("warnings_enabled", "hard_stop_enabled", "non_interactive_hard_stop_enabled")
  59. # Threshold field -> (nested section, nested key). The flat legacy key is the field name itself.
  60. _THRESHOLD_SOURCES: dict[str, tuple[str, str]] = {
  61. "exact_failure_warn_after": ("warn_after", "exact_failure"),
  62. "same_tool_failure_warn_after": ("warn_after", "same_tool_failure"),
  63. "no_progress_warn_after": ("warn_after", "idempotent_no_progress"),
  64. "exact_failure_block_after": ("hard_stop_after", "exact_failure"),
  65. "same_tool_failure_halt_after": ("hard_stop_after", "same_tool_failure"),
  66. "no_progress_block_after": ("hard_stop_after", "idempotent_no_progress"),
  67. }
  68. # Per-turn caps on runaway-prone tools (counters reset in reset_for_turn).
  69. _DEFAULT_MAX_WEB_SEARCHES_PER_TURN = 50
  70. _DEFAULT_MAX_SUBAGENTS_PER_TURN = 50
  71. # Interactive surfaces plus bounded supervised task loops (subagent stopped by its parent;
  72. # api_server has a live client) doing real edit -> re-run work keep the warn-only default.
  73. _ATTENDED_PLATFORMS = frozenset({"cli", "tui", "desktop", "acp", "subagent", "api_server"})
  74. def is_stall_guard_repeatable(tool_name: str) -> bool:
  75. """Whether a tool is exempt from the identical-call loop notice."""
  76. return tool_name in STALL_GUARD_REPEATABLE_TOOLS or tool_name.endswith(_STALL_GUARD_REPEATABLE_SUFFIXES)
  77. def _is_non_interactive_platform(platform: str | None) -> bool:
  78. """True for gateway/cron sessions where tool loops are unattended."""
  79. if not isinstance(platform, str) or not platform.strip():
  80. return False
  81. return platform.strip().lower() not in _ATTENDED_PLATFORMS
  82. @dataclass(frozen=True)
  83. class LoopCapConfig:
  84. """Per-turn hard ceilings on web_search calls / subagent spawns; count total calls (not
  85. repeats), fire regardless of ``hard_stop_enabled``; ``0`` disables a cap."""
  86. max_web_searches: int = _DEFAULT_MAX_WEB_SEARCHES_PER_TURN
  87. max_subagents: int = _DEFAULT_MAX_SUBAGENTS_PER_TURN
  88. @classmethod
  89. def from_mapping(cls, data: Mapping[str, Any] | None) -> LoopCapConfig:
  90. """Build config from the ``tool_loop_guardrails.loop_caps`` section."""
  91. if not isinstance(data, Mapping):
  92. return cls()
  93. return cls(**{f.name: _int_at_least(data.get(f.name), f.default, 0) for f in fields(cls)})
  94. @dataclass(frozen=True)
  95. class ToolCallGuardrailConfig:
  96. """Thresholds for per-turn tool-call loop detection. Warnings never prevent execution; hard
  97. stops are opt-in on interactive platforms, default on for unattended gateway/cron platforms."""
  98. warnings_enabled: bool = True
  99. hard_stop_enabled: bool = False
  100. non_interactive_hard_stop_enabled: bool = True
  101. exact_failure_warn_after: int = 2
  102. exact_failure_block_after: int = 5
  103. same_tool_failure_warn_after: int = 3
  104. same_tool_failure_halt_after: int = 8
  105. no_progress_warn_after: int = 2
  106. no_progress_block_after: int = 5
  107. idempotent_tools: frozenset[str] = field(default_factory=lambda: IDEMPOTENT_TOOL_NAMES)
  108. mutating_tools: frozenset[str] = field(default_factory=lambda: MUTATING_TOOL_NAMES)
  109. loop_caps: LoopCapConfig = field(default_factory=LoopCapConfig)
  110. @classmethod
  111. def from_mapping(
  112. cls, data: Mapping[str, Any] | None, *, platform: str | None = None,
  113. ) -> ToolCallGuardrailConfig:
  114. """Build config from `tool_loop_guardrails`; nested ``warn_after`` / ``hard_stop_after`` win over flat legacy keys."""
  115. if not isinstance(data, Mapping):
  116. data = {}
  117. d = cls()
  118. flags = {name: _as_bool(data.get(name), getattr(d, name)) for name in _BOOL_FIELDS}
  119. if flags["non_interactive_hard_stop_enabled"] and _is_non_interactive_platform(platform):
  120. flags["hard_stop_enabled"] = True
  121. def threshold(name: str, section_name: str, key: str) -> int:
  122. section = data.get(section_name)
  123. nested = section.get(key, data.get(name)) if isinstance(section, Mapping) else data.get(name)
  124. return _int_at_least(nested, getattr(d, name), 1)
  125. thresholds = {name: threshold(name, *src) for name, src in _THRESHOLD_SOURCES.items()}
  126. return cls(loop_caps=LoopCapConfig.from_mapping(data.get("loop_caps")), **flags, **thresholds)
  127. @dataclass(frozen=True)
  128. class IdenticalCallObservation:
  129. """``notice`` is appended after the result, ``stub`` replaces a byte-identical duplicate result;
  130. ``kind`` names the detector behind the notice (``identical_call_streak`` / ``identical_cycle``)."""
  131. notice: str | None = None
  132. stub: str | None = None
  133. kind: str | None = None
  134. @dataclass(frozen=True)
  135. class ToolCallSignature:
  136. """Stable, non-reversible identity for a tool name plus canonical args."""
  137. tool_name: str
  138. args_hash: str
  139. @classmethod
  140. def from_call(cls, tool_name: str, args: Mapping[str, Any] | None) -> ToolCallSignature:
  141. return cls(tool_name=tool_name, args_hash=_sha256(canonical_tool_args(args or {})))
  142. def to_metadata(self) -> dict[str, str]:
  143. """Return public metadata without raw argument values."""
  144. return asdict(self)
  145. @dataclass(frozen=True)
  146. class ToolGuardrailDecision:
  147. """Decision returned by the tool-call guardrail controller."""
  148. action: str = "allow" # allow | warn | block | halt
  149. code: str = "allow"
  150. message: str = ""
  151. tool_name: str = ""
  152. count: int = 0
  153. signature: ToolCallSignature | None = None
  154. @property
  155. def allows_execution(self) -> bool:
  156. return self.action in {"allow", "warn"}
  157. @property
  158. def should_halt(self) -> bool:
  159. return self.action in {"block", "halt"}
  160. def to_metadata(self) -> dict[str, Any]:
  161. data = asdict(self)
  162. if data["signature"] is None:
  163. del data["signature"]
  164. return data
  165. def _canonical_json(value: Any) -> str:
  166. return json.dumps(value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), default=str)
  167. def canonical_tool_args(args: Mapping[str, Any]) -> str:
  168. """Return sorted compact JSON for parsed tool arguments."""
  169. if not isinstance(args, Mapping):
  170. raise TypeError(f"tool args must be a mapping, got {type(args).__name__}")
  171. return _canonical_json(args)
  172. def classify_tool_failure(tool_name: str, result: str | None) -> tuple[bool, str]:
  173. """Fallback classifier used only when callers don't pass ``failed``; mirrors
  174. ``agent.display._detect_tool_failure`` so the guardrail never disagrees with the CLI's ``[error]`` tag."""
  175. if result is None or file_mutation_result_landed(tool_name, result):
  176. return False, ""
  177. # A harness REFUSAL of a redundant call (repeated identical read/search) carries
  178. # ``"error"`` for the model's benefit -- exactly what the substring test below keys
  179. # on -- but nothing failed; counting it lets the cheap refusal feed the streak that
  180. # fires the next, harder one. Mirrored in ``agent.display._detect_tool_failure``.
  181. if is_guardrail_refusal(result):
  182. return False, ""
  183. if tool_name == "terminal":
  184. data = safe_json_loads(result)
  185. exit_code = data.get("exit_code") if isinstance(data, dict) else None
  186. return (True, f" [exit {exit_code}]") if exit_code is not None and exit_code != 0 else (False, "")
  187. data = safe_json_loads(result)
  188. if isinstance(data, dict):
  189. failed = data.get("success") is False
  190. if tool_name == "memory" and failed and "exceed the limit" in data.get("error", ""):
  191. return True, " [full]"
  192. # Same rule as _detect_tool_failure: a JSON object is judged by its top-level
  193. # shape, never by a substring scan of its nested content.
  194. err = data.get("error") or data.get("message")
  195. return (True, " [error]") if (err and (failed or "error" in data)) or shape_failure_error(data) else (False, "")
  196. return (True, " [error]") if has_failure_marker(result) else (False, "")
  197. # Guardrail verdict text injected into the conversation, keyed by decision code.
  198. # ``same_tool_failure_warning`` is built by _tool_failure_recovery_hint (tool-specific).
  199. _DECISION_MESSAGES: dict[str, str] = {
  200. "repeated_exact_failure_block": (
  201. "Blocked {tool_name}: the same tool call failed {count} times with identical arguments. "
  202. "Stop retrying it unchanged; change strategy or explain the blocker."
  203. ),
  204. "idempotent_no_progress_block": (
  205. "Blocked {tool_name}: this read-only call returned the same result {count} times. "
  206. "Stop repeating it unchanged; use the result already provided or try a different query."
  207. ),
  208. "same_tool_failure_halt": (
  209. "Stopped {tool_name}: it failed {count} times this turn. "
  210. "Stop retrying the same failing tool path and choose a different approach."
  211. ),
  212. "repeated_exact_failure_warning": (
  213. "{tool_name} has failed {count} times with identical arguments. This looks like a loop; "
  214. "inspect the error and change strategy instead of retrying it unchanged."
  215. ),
  216. "idempotent_no_progress_warning": (
  217. "{tool_name} returned the same result {count} times. Use the result already provided "
  218. "or change the query instead of repeating it unchanged."
  219. ),
  220. "identical_call_streak_halt": (
  221. "Stopped {tool_name}: the same call with identical arguments returned the same result "
  222. "{count} times in a row. Stop repeating it unchanged; use the result already provided or change strategy."
  223. ),
  224. "identical_cycle_halt": (
  225. "Stopped {tool_name}: the same repeating cycle of tool calls (period {period}) with identical "
  226. "arguments and identical results has run {count} times. Repeating the batch unchanged is not "
  227. "progress; use the results already provided or change strategy."
  228. ),
  229. "loop_web_search_cap": (
  230. "Blocked web_search: this turn has already made {cap} web searches, the per-turn limit. "
  231. "This looks like a runaway search loop. Work with the results you already have and give the user your answer."
  232. ),
  233. "loop_subagent_cap": (
  234. "Blocked delegate_task: this turn has already spawned {count} subagents (limit {cap}). "
  235. "This looks like a runaway delegation loop. Finish the work with the results you have and answer the user."
  236. ),
  237. }
  238. _IDENTICAL_CALL_NOTICE = (
  239. "[hermes note: this is the {ordinal} consecutive identical call to "
  240. "{tool_name} with identical arguments returning the same result. "
  241. "Do not repeat it — change arguments, use a different tool, or "
  242. "proceed with what you have.]"
  243. )
  244. _IDENTICAL_CYCLE_NOTICE = (
  245. "[hermes note: the last {count} rounds repeated the same cycle of {period} tool calls "
  246. "(ending with {tool_name}) with identical arguments and identical results. "
  247. "Do not repeat the batch — change arguments, use a different tool, or "
  248. "proceed with what you have.]"
  249. )
  250. # tool -> (LoopCapConfig field, controller counter attribute, decision code)
  251. _LOOP_CAPS: dict[str, tuple[str, str, str]] = {
  252. "web_search": ("max_web_searches", "_turn_web_search_count", "loop_web_search_cap"),
  253. "delegate_task": ("max_subagents", "_turn_subagent_count", "loop_subagent_cap"),
  254. }
  255. class ToolCallGuardrailController:
  256. """Per-turn controller for repeated failed/non-progressing tool calls."""
  257. def __init__(self, config: ToolCallGuardrailConfig | None = None):
  258. self.config = config or ToolCallGuardrailConfig()
  259. self.reset_for_turn()
  260. def reset_for_turn(self) -> None:
  261. self._exact_failure_counts: dict[ToolCallSignature, int] = {}
  262. self._same_tool_failure_counts: dict[str, int] = {}
  263. # signature -> a mutating call succeeded since its last failure
  264. self._progress_since_failure: dict[ToolCallSignature, bool] = {}
  265. self._no_progress: dict[ToolCallSignature, tuple[str, int]] = {}
  266. self._halt_decision: ToolGuardrailDecision | None = None
  267. # Identical-call streak: CONSECUTIVE identical (tool, args, result) calls; any different call or
  268. # result resets it, so re-reads after edits and varied polling are never flagged.
  269. # Identical-call loop-breaker state (agent.stall_guards): tracks the CONSECUTIVE streak of identical
  270. # (tool, canonical args) calls whose results were also identical. Per-turn, like everything else
  271. # here. NOTE: open PR #85352 (patrykkopycinski) tracks no-progress loops ACROSS turns via a
  272. # detection window — a different mechanism from this per-turn consecutive streak. Coordinate future
  273. # work there.
  274. self._identical_streak_sig: ToolCallSignature | None = None
  275. self._identical_streak_result_hash: str = ""
  276. self._identical_streak_count: int = 0
  277. self._identical_streak_first_call_id: str = ""
  278. # Batch-cycle loop breaker (port of can1357/oh-my-pi#10521): sequence of
  279. # (signature, result_hash, repeatable) for every observed call this turn, so a repeating
  280. # multi-call cycle (A,B,A,B,...) is caught even though it resets the consecutive streak above.
  281. self._call_history: deque[tuple[ToolCallSignature, str, bool]] = deque(maxlen=_STALL_GUARD_CYCLE_HISTORY)
  282. # tool_call_id -> spillover path, so a stub referencing a persisted-output preview can't dangle.
  283. self._persisted_result_paths: dict[str, str] = {}
  284. self._turn_web_search_count = 0
  285. self._turn_subagent_count = 0
  286. @property
  287. def halt_decision(self) -> ToolGuardrailDecision | None:
  288. return self._halt_decision
  289. def _decide(
  290. self, action: str, code: str, tool_name: str, count: int, signature: ToolCallSignature,
  291. *, message: str | None = None, **fmt: Any,
  292. ) -> ToolGuardrailDecision:
  293. """Build a warn/block/halt decision; block/halt is also recorded as the turn's halt decision."""
  294. if message is None:
  295. message = _DECISION_MESSAGES[code].format(tool_name=tool_name, count=count, **fmt)
  296. decision = ToolGuardrailDecision(action, code, message, tool_name, count, signature)
  297. if decision.should_halt:
  298. self._halt_decision = decision
  299. return decision
  300. def before_call(self, tool_name: str, args: Mapping[str, Any] | None) -> ToolGuardrailDecision:
  301. args = _coerce_args(args)
  302. signature = ToolCallSignature.from_call(tool_name, args)
  303. allow = ToolGuardrailDecision(tool_name=tool_name, signature=signature)
  304. # Loop caps apply regardless of hard_stop_enabled (which only governs the detector).
  305. cap_block = self._check_loop_cap(tool_name, args, signature)
  306. if cap_block is not None or not self.config.hard_stop_enabled:
  307. return cap_block or allow
  308. # A mutation since this call last failed makes the retry a new experiment.
  309. exact_count = 0 if self._progress_since_failure.get(signature) else self._exact_failure_counts.get(signature, 0)
  310. if exact_count >= self.config.exact_failure_block_after:
  311. return self._decide("block", "repeated_exact_failure_block", tool_name, exact_count, signature)
  312. record = self._no_progress.get(signature) if self._is_idempotent(tool_name) else None
  313. if record is not None and record[1] >= self.config.no_progress_block_after:
  314. return self._decide("block", "idempotent_no_progress_block", tool_name, record[1], signature)
  315. return allow
  316. def after_call(
  317. self, tool_name: str, args: Mapping[str, Any] | None, result: str | None,
  318. *, failed: bool | None = None,
  319. ) -> ToolGuardrailDecision:
  320. args = _coerce_args(args)
  321. signature = ToolCallSignature.from_call(tool_name, args)
  322. if failed is None:
  323. failed, _ = classify_tool_failure(tool_name, result)
  324. warnings = self.config.warnings_enabled
  325. if failed:
  326. # An identical failing call is only a REPLAY if nothing landed in between;
  327. # a mutation since the last identical failure restarts the exact-args streak.
  328. if self._progress_since_failure.pop(signature, False):
  329. self._exact_failure_counts.pop(signature, None)
  330. # A throttled call retried after its cooldown is the correct move, not a replay:
  331. # keep it out of the exact-args streak and never give it that streak's "stop retrying
  332. # unchanged" warning, even after earlier ordinary failures with the same args.
  333. # It still counts per tool below, so same_tool_failure_halt bounds a dead endpoint.
  334. throttled = is_rate_limited(result)
  335. exact_count = self._exact_failure_counts.get(signature, 0)
  336. if not throttled:
  337. exact_count = self._exact_failure_counts[signature] = exact_count + 1
  338. same_count = self._same_tool_failure_counts[tool_name] = self._same_tool_failure_counts.get(tool_name, 0) + 1
  339. self._no_progress.pop(signature, None)
  340. # same_tool_failure counts DIFFERENT args on one tool; for failure-tolerant
  341. # tools a run of distinct red commands is diagnosis, not a loop — warn, never halt.
  342. if (
  343. # Hard-stop widening (#89069 / #100849 bundle): the per-turn no-progress BLOCK above only
  344. # covers tools in idempotent_tools, so a model replaying the same successful
  345. # `terminal`/`skill_view` call with a byte-identical result ran until the iteration budget.
  346. # The consecutive-identical streak is tool-agnostic; when hard stops are enabled, halt at
  347. # the same idempotent_no_progress threshold. Pollers stay exempt (an unchanged poll is
  348. # progress).
  349. self.config.hard_stop_enabled
  350. and tool_name not in FAILURE_TOLERANT_TOOL_NAMES
  351. and same_count >= self.config.same_tool_failure_halt_after
  352. ):
  353. return self._decide("halt", "same_tool_failure_halt", tool_name, same_count, signature)
  354. if warnings and not throttled and exact_count >= self.config.exact_failure_warn_after:
  355. return self._decide("warn", "repeated_exact_failure_warning", tool_name, exact_count, signature)
  356. if warnings and same_count >= self.config.same_tool_failure_warn_after:
  357. return self._decide(
  358. "warn", "same_tool_failure_warning", tool_name, same_count, signature,
  359. message=_tool_failure_recovery_hint(tool_name, same_count),
  360. )
  361. return ToolGuardrailDecision(tool_name=tool_name, count=exact_count, signature=signature)
  362. self._exact_failure_counts.pop(signature, None)
  363. self._same_tool_failure_counts.pop(tool_name, None)
  364. # A successful mutation is progress for every failing signature still counted
  365. # this turn. Pure loops never mutate between attempts, so the replay detector keeps its teeth.
  366. if tool_name in PROGRESS_RESET_TOOL_NAMES or file_mutation_result_landed(tool_name, result):
  367. self._progress_since_failure.update(dict.fromkeys(self._exact_failure_counts, True))
  368. self._same_tool_failure_counts.clear()
  369. if not self._is_idempotent(tool_name):
  370. self._no_progress.pop(signature, None)
  371. return ToolGuardrailDecision(tool_name=tool_name, signature=signature)
  372. result_hash = _result_hash(result, tool_name)
  373. previous = self._no_progress.get(signature)
  374. repeat_count = previous[1] + 1 if previous is not None and previous[0] == result_hash else 1
  375. self._no_progress[signature] = (result_hash, repeat_count)
  376. if warnings and repeat_count >= self.config.no_progress_warn_after:
  377. return self._decide("warn", "idempotent_no_progress_warning", tool_name, repeat_count, signature)
  378. return ToolGuardrailDecision(tool_name=tool_name, count=repeat_count, signature=signature)
  379. def _is_idempotent(self, tool_name: str) -> bool:
  380. return tool_name not in self.config.mutating_tools and tool_name in self.config.idempotent_tools
  381. def observe_call(
  382. self, tool_name: str, args: Mapping[str, Any] | None, result: str | None,
  383. *, tool_call_id: str = "", failed: bool = False,
  384. ) -> IdenticalCallObservation:
  385. """Track consecutive identical calls; return notice + dedupe stub info.
  386. ``notice`` fires from the threshold-th consecutive identical (tool, args, result) call
  387. (observational, pollers exempt). ``stub`` replaces the CURRENT result from the 2nd byte-identical
  388. repeat — the tool still executed, only the context representation is deduplicated, so polling
  389. semantics survive; pollers are NOT exempt here since an unchanged poll is where it saves most.
  390. """
  391. is_plain_str = isinstance(result, str)
  392. signature = ToolCallSignature.from_call(tool_name, _coerce_args(args))
  393. result_hash = _result_hash(result, tool_name) if is_plain_str else ""
  394. if is_plain_str and (signature, result_hash) == (self._identical_streak_sig, self._identical_streak_result_hash):
  395. self._identical_streak_count += 1
  396. else:
  397. # New streak; non-string (multimodal) results never form one.
  398. self._identical_streak_sig = signature if is_plain_str else None
  399. self._identical_streak_result_hash = result_hash
  400. self._identical_streak_count = 1 if is_plain_str else 0
  401. self._identical_streak_first_call_id = tool_call_id or ""
  402. count = self._identical_streak_count
  403. notice = kind = None
  404. if not is_stall_guard_repeatable(tool_name) and count >= STALL_GUARD_IDENTICAL_CALL_THRESHOLD:
  405. notice, kind = _IDENTICAL_CALL_NOTICE.format(ordinal=_ordinal(count), tool_name=tool_name), "identical_call_streak"
  406. # The no-progress BLOCK in before_call only covers idempotent_tools; this streak
  407. # is tool-agnostic, so with hard stops on, halt at the same threshold (a model
  408. # replaying a successful `terminal` call otherwise runs to the budget).
  409. if self.config.hard_stop_enabled and count >= self.config.no_progress_block_after and self._halt_decision is None:
  410. self._decide("halt", "identical_call_streak_halt", tool_name, count, signature)
  411. # Batch-cycle detection (oh-my-pi#10521): a repeating multi-call cycle resets the
  412. # consecutive streak on every alternation, so check the call history for a period-p lap.
  413. if is_plain_str:
  414. self._call_history.append((signature, result_hash, is_stall_guard_repeatable(tool_name)))
  415. else:
  416. self._call_history.clear()
  417. if notice is None and is_plain_str:
  418. cycle = self._detect_identical_cycle()
  419. if cycle is not None:
  420. period, laps = cycle
  421. notice, kind = _IDENTICAL_CYCLE_NOTICE.format(count=laps, period=period, tool_name=tool_name), "identical_cycle"
  422. if self.config.hard_stop_enabled and laps >= self.config.no_progress_block_after and self._halt_decision is None:
  423. self._decide("halt", "identical_cycle_halt", tool_name, laps, signature, period=period)
  424. stub = None
  425. if is_plain_str and count >= 2 and not failed and len(result) >= IDENTICAL_RESULT_STUB_MIN_CHARS:
  426. stub = self._build_result_reference_stub(tool_name, args)
  427. return IdenticalCallObservation(notice=notice, stub=stub, kind=kind)
  428. def _detect_identical_cycle(self) -> tuple[int, int] | None:
  429. """Detect a repeating identical-call cycle ending at the latest observed call.
  430. Returns ``(period, laps)`` for the smallest period 2..max whose trailing laps
  431. (identical signature AND result per position) reach the notice threshold, else None.
  432. Period 1 is the consecutive streak's job. A cycle made ONLY of poller-exempt tools
  433. is exempt (an unchanged poll loop is legitimate waiting); one non-exempt call in
  434. the cycle keeps the guard armed, matching the single-call exemption semantics.
  435. """
  436. history = self._call_history
  437. for period in range(2, _STALL_GUARD_MAX_CYCLE_PERIOD + 1):
  438. if len(history) < period * STALL_GUARD_IDENTICAL_CALL_THRESHOLD:
  439. continue
  440. laps = 1
  441. # Count how many consecutive trailing laps equal the final lap.
  442. while True:
  443. base = len(history) - period * (laps + 1)
  444. if base < 0:
  445. break
  446. lap_equal = all(
  447. history[base + i][:2] == history[len(history) - period + i][:2]
  448. for i in range(period)
  449. )
  450. if not lap_equal:
  451. break
  452. laps += 1
  453. if laps >= STALL_GUARD_IDENTICAL_CALL_THRESHOLD:
  454. tail = [history[len(history) - period + i] for i in range(period)]
  455. if all(repeatable for _, _, repeatable in tail):
  456. continue
  457. # A constant sub-cycle would already have fired at a smaller period.
  458. return period, laps
  459. return None
  460. def record_persisted_result(self, tool_call_id: str, file_path: str) -> None:
  461. """Remember the spillover path a persisted result was saved to."""
  462. if tool_call_id and file_path:
  463. self._persisted_result_paths[tool_call_id] = file_path
  464. def _build_result_reference_stub(self, tool_name: str, args: Mapping[str, Any] | None) -> str:
  465. """Reference stub for a byte-identical duplicate result (tool + args preview)."""
  466. args_preview = canonical_tool_args(_coerce_args(args))
  467. if len(args_preview) > _RESULT_STUB_ARGS_PREVIEW_CHARS:
  468. args_preview = args_preview[:_RESULT_STUB_ARGS_PREVIEW_CHARS] + "…"
  469. first_id = self._identical_streak_first_call_id
  470. ref = f" (tool_call_id {first_id})" if first_id else ""
  471. stub = (
  472. f"[hermes note: this result is byte-identical to the {tool_name} "
  473. f"result earlier this turn{ref}. Refer to that result; it has not "
  474. f"changed. Args: {args_preview}]"
  475. )
  476. spill_path = self._persisted_result_paths.get(first_id) if first_id else None
  477. if spill_path:
  478. stub += f"\n[The referenced result was persisted to: {spill_path} — page through it with read_file if you need the full content.]"
  479. return stub
  480. def _check_loop_cap(
  481. self, tool_name: str, args: Mapping[str, Any], signature: ToolCallSignature,
  482. ) -> ToolGuardrailDecision | None:
  483. """Block once a per-turn cap is reached (BEFORE the call, so the (cap+1)-th is refused), else advance
  484. the counter and return None. delegate_task control actions spawn nothing and keep working after the cap."""
  485. spec = _LOOP_CAPS.get(tool_name)
  486. if spec is None:
  487. return None
  488. cap_field, count_attr, code = spec
  489. cap, count = getattr(self.config.loop_caps, cap_field), getattr(self, count_attr)
  490. increment = 1 if tool_name == "web_search" else (_subagent_spawn_count(args) if cap else 0)
  491. if increment and cap and count >= cap:
  492. return self._decide("block", code, tool_name, count, signature, cap=cap)
  493. setattr(self, count_attr, count + increment)
  494. return None
  495. def toolguard_synthetic_result(decision: ToolGuardrailDecision) -> str:
  496. """Build a synthetic role=tool content string for a blocked tool call."""
  497. return json.dumps({"error": decision.message, "guardrail": decision.to_metadata()}, ensure_ascii=False)
  498. def append_toolguard_guidance(result: str, decision: ToolGuardrailDecision) -> str:
  499. """Append runtime guidance to the current tool result content."""
  500. if decision.action not in {"warn", "halt"} or not decision.message:
  501. return result
  502. label = "Tool loop hard stop" if decision.action == "halt" else "Tool loop warning"
  503. return (result or "") + f"\n\n[{label}: {decision.code}; count={decision.count}; {decision.message}]"
  504. def _tool_failure_recovery_hint(tool_name: str, count: int) -> str:
  505. """Action-oriented guidance for recovering from repeated tool failures."""
  506. common = (
  507. f"{tool_name} has failed {count} times this turn. This looks like a loop. "
  508. "Do not switch to text-only replies; keep using tools, but diagnose before retrying. "
  509. "First inspect the latest error/output and verify your assumptions. "
  510. )
  511. if tool_name == "terminal":
  512. return common + (
  513. "For terminal failures, run a small diagnostic such as `pwd && ls -la` "
  514. "in the same tool, then try an absolute path, a simpler command, a different "
  515. "working directory, or a different tool such as read_file/write_file/patch."
  516. )
  517. return common + (
  518. "Try different arguments, a narrower query/path, an absolute path when relevant, "
  519. "or a different tool that can make progress. If the blocker is external, report "
  520. "the blocker after one diagnostic attempt instead of repeating the same failing path."
  521. )
  522. def _ordinal(count: int) -> str:
  523. return f"{count}{'th' if 11 <= count % 100 <= 13 else {1: 'st', 2: 'nd', 3: 'rd'}.get(count % 10, 'th')}"
  524. def _coerce_args(args: Mapping[str, Any] | None) -> Mapping[str, Any]:
  525. return args if isinstance(args, Mapping) else {}
  526. # execute_code reports per-call kernel bookkeeping — a running `kernel.execution_count` and wall-clock
  527. # `duration_seconds` — that changes on every invocation even when the code did the same thing. Hashed
  528. # as-is, every replay of an identical empty probe looks new and the identical-call streak never forms
  529. # (a model re-ran one empty execute_code call 147 times unflagged). Only these known locations in
  530. # execute_code's own result shape are dropped: for any other tool the same key names can be real output.
  531. def _without_execute_code_metadata(parsed: Any) -> Any:
  532. if not isinstance(parsed, dict):
  533. return parsed
  534. cleaned = {k: v for k, v in parsed.items() if k != "duration_seconds"}
  535. kernel = cleaned.get("kernel")
  536. if isinstance(kernel, dict):
  537. cleaned["kernel"] = {k: v for k, v in kernel.items() if k != "execution_count"}
  538. return cleaned
  539. def _result_hash(result: str | None, tool_name: str = "") -> str:
  540. parsed = safe_json_loads(result or "")
  541. if parsed is None:
  542. return _sha256(result or "")
  543. if tool_name == "execute_code":
  544. parsed = _without_execute_code_metadata(parsed)
  545. return _sha256(_canonical_json(parsed))
  546. _BOOL_WORDS = {w: True for w in ("1", "true", "yes", "on", "enabled")} | {w: False for w in ("0", "false", "no", "off", "disabled")}
  547. def _as_bool(value: Any, default: bool) -> bool:
  548. if isinstance(value, (bool, int, float)):
  549. return bool(value)
  550. if isinstance(value, str):
  551. return _BOOL_WORDS.get(value.strip().lower(), default)
  552. return default
  553. def _int_at_least(value: Any, default: int, minimum: int) -> int:
  554. """junk/None/below-minimum fall back to default (caps use minimum 0 so 0 = disabled)."""
  555. try:
  556. parsed = int(value)
  557. except (TypeError, ValueError):
  558. return default
  559. return parsed if parsed >= minimum else default
  560. def _subagent_spawn_count(args: Mapping[str, Any]) -> int:
  561. """Subagents one delegate_task call spawns: ``len(tasks)`` for a non-empty batch, else 1; control actions 0."""
  562. if str(args.get("action") or "").strip().lower() in ("list", "steer", "stop"):
  563. return 0
  564. tasks = args.get("tasks")
  565. return len(tasks) if isinstance(tasks, list) and tasks else 1
  566. def _sha256(value: str) -> str:
  567. # surrogatepass: web-scraped results can carry unpaired UTF-16 surrogates; a
  568. # strict encode would raise and take down the conversation loop.
  569. return hashlib.sha256(value.encode("utf-8", "surrogatepass")).hexdigest()