mirrors/hermes-agent
1
0
Fork 0
mirror of https://github.com/NousResearch/hermes-agent.git synced 2026-07-27 17:58:07 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

refactor(guardrails): make runaway-loop caps per-turn, not session-total

Browse source 
Per Teknium: the caps should bound a single agent loop, not accumulate
over the whole session. Rename SessionCapConfig -> LoopCapConfig and the
config section session_caps -> loop_caps; move the counters into
reset_for_turn (invoked per turn via turn_context) so each turn starts
with a fresh budget; retune defaults 200 -> 50 (a single turn issuing 50
web searches / spawning 50 subagents is already pathological). Block
codes session_*_cap -> loop_*_cap and messages updated to drop the
/new-resets-the-budget guidance (irrelevant now that it resets per turn).
Tests flipped: the old persists-across-turn-resets assertion becomes
resets-each-turn.
This commit is contained in:
teknium1 2026-07-26 20:57:58 -07:00 • committed by Teknium
parent b68787ad25
commit cb06017b1d
4 changed files with 117 additions and 97 deletions
Download patch file Download diff file Expand all files Collapse all files

109
agent/tool_guardrails.py
View file

@ -79,7 +79,7 @@ class ToolCallGuardrailConfig:
no_progress_block_after: int = 5
idempotent_tools: frozenset[str] = field(default_factory=lambda: IDEMPOTENT_TOOL_NAMES)
mutating_tools: frozenset[str] = field(default_factory=lambda: MUTATING_TOOL_NAMES)
session_caps: "SessionCapConfig" = field(default_factory=lambda: SessionCapConfig())
loop_caps: "LoopCapConfig" = field(default_factory=lambda: LoopCapConfig())
@classmethod
def from_mapping(cls, data: Mapping[str, Any] | None) -> "ToolCallGuardrailConfig":
@ -122,41 +122,44 @@ class ToolCallGuardrailConfig:
hard_stop_after.get("idempotent_no_progress", data.get("no_progress_block_after")),
defaults.no_progress_block_after,
),
session_caps=SessionCapConfig.from_mapping(data.get("session_caps")),
loop_caps=LoopCapConfig.from_mapping(data.get("loop_caps")),
)
# Default session-wide caps, matching Claude Code's v2.1.212 runaway-loop
# limits (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION /
# CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION, both default 200, reset on /clear).
_DEFAULT_MAX_WEB_SEARCHES_PER_SESSION = 200
_DEFAULT_MAX_SUBAGENTS_PER_SESSION = 200
# Per-turn (per-agent-loop) caps on runaway-prone tool calls. Counts reset at
# the start of every agent loop (reset_for_turn), so the limit is "within a
# single turn" rather than cumulative over the whole session. A single loop
# issuing dozens of web searches or spawning dozens of subagents is already
# pathological, so the defaults are deliberately low.
_DEFAULT_MAX_WEB_SEARCHES_PER_TURN = 50
_DEFAULT_MAX_SUBAGENTS_PER_TURN = 50
@dataclass(frozen=True)
class SessionCapConfig:
"""Session-wide lifetime caps on runaway-prone tool calls.
class LoopCapConfig:
"""Per-turn caps on runaway-prone tool calls.
Inspired by Claude Code v2.1.212 (Week 29, July 2026), which added a
per-session cap on WebSearch calls and subagent spawns to stop runaway
search / delegation loops. These caps count over the whole session (not
per turn like the loop-detection guardrails above) and reset only when a
fresh agent is created — i.e. on ``/new`` or ``/clear`` — because the
counters live on the ``AIAgent`` instance, not in ``reset_for_turn``.
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 guardrails: session caps are a
hard safety ceiling and fire regardless of ``hard_stop_enabled``. A value
of ``0`` disables the cap (unlimited). Defaults match Claude Code (200);
a legitimate session almost never issues 200 web searches or spawns 200
subagents, so hitting the cap is a strong runaway-loop signal.
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).
"""
max_web_searches: int = _DEFAULT_MAX_WEB_SEARCHES_PER_SESSION
max_subagents: int = _DEFAULT_MAX_SUBAGENTS_PER_SESSION
max_web_searches: int = _DEFAULT_MAX_WEB_SEARCHES_PER_TURN
max_subagents: int = _DEFAULT_MAX_SUBAGENTS_PER_TURN
@classmethod
def from_mapping(cls, data: Mapping[str, Any] | None) -> "SessionCapConfig":
"""Build config from the ``tool_loop_guardrails.session_caps`` section."""
def from_mapping(cls, data: Mapping[str, Any] | None) -> "LoopCapConfig":
"""Build config from the ``tool_loop_guardrails.loop_caps`` section."""
if not isinstance(data, Mapping):
return cls()
defaults = cls()
@ -272,12 +275,6 @@ class ToolCallGuardrailController:
def __init__(self, config: ToolCallGuardrailConfig | None = None):
self.config = config or ToolCallGuardrailConfig()
# Session-wide counters persist for the life of this controller (i.e.
# the life of the AIAgent instance). They are deliberately NOT cleared
# in reset_for_turn — a runaway loop that spans many turns must still be
# caught. They reset only when a fresh agent is built (/new, /clear).
self._session_web_search_count = 0
self._session_subagent_count = 0
self.reset_for_turn()
def reset_for_turn(self) -> None:
@ -285,6 +282,11 @@ class ToolCallGuardrailController:
self._same_tool_failure_counts: dict[str, int] = {}
self._no_progress: dict[ToolCallSignature, tuple[str, int]] = {}
self._halt_decision: ToolGuardrailDecision | None = None
# Per-turn runaway-loop cap counters. Reset every turn (this method
# runs at the start of each run_conversation), so the caps bound a
# single agent loop rather than accumulating across the session.
self._turn_web_search_count = 0
self._turn_subagent_count = 0
@property
def halt_decision(self) -> ToolGuardrailDecision | None:
@ -293,12 +295,13 @@ class ToolCallGuardrailController:
def before_call(self, tool_name: str, args: Mapping[str, Any] | None) -> ToolGuardrailDecision:
signature = ToolCallSignature.from_call(tool_name, _coerce_args(args))
# ── Session-wide runaway-loop caps ──────────────────────────────
# These are hard safety ceilings that apply regardless of
# hard_stop_enabled (which only governs the per-turn loop detector).
# ── Per-turn runaway-loop caps ──────────────────────────────────
# These are hard ceilings on how many times a runaway-prone tool may
# be called within a single agent loop (turn). They apply regardless
# of hard_stop_enabled (which only governs the per-turn loop detector).
# We block BEFORE the call runs once the count is already at the cap,
# then increment for an allowed call so the (cap+1)-th is refused.
cap_block = self._check_session_cap(tool_name, _coerce_args(args), signature)
cap_block = self._check_loop_cap(tool_name, _coerce_args(args), signature)
if cap_block is not None:
return cap_block
@ -441,39 +444,40 @@ class ToolCallGuardrailController:
return False
return tool_name in self.config.idempotent_tools
def _check_session_cap(
def _check_loop_cap(
self,
tool_name: str,
args: Mapping[str, Any],
signature: ToolCallSignature,
) -> ToolGuardrailDecision | None:
"""Enforce and advance the session-wide runaway-loop counters.
"""Enforce 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.
``None``. A cap of 0 disables that limit entirely. Counters reset each
turn via ``reset_for_turn``.
"""
caps = self.config.session_caps
caps = self.config.loop_caps
if tool_name == "web_search":
cap = caps.max_web_searches
if cap and self._session_web_search_count >= cap:
if cap and self._turn_web_search_count >= cap:
decision = ToolGuardrailDecision(
action="block",
code="session_web_search_cap",
code="loop_web_search_cap",
message=(
f"Blocked web_search: this session has already made {cap} "
"web searches, the per-session limit. This looks like a "
f"Blocked web_search: this turn has already made {cap} "
"web searches, the per-turn limit. This looks like a "
"runaway search loop. Work with the results you already "
"have, or start a fresh session (/new) to reset the budget."
"have and give the user your answer."
),
tool_name=tool_name,
count=self._session_web_search_count,
count=self._turn_web_search_count,
signature=signature,
)
self._halt_decision = decision
return decision
self._session_web_search_count += 1
self._turn_web_search_count += 1
return None
if tool_name == "delegate_task":
@ -481,24 +485,23 @@ class ToolCallGuardrailController:
if not cap:
return None
spawn_count = _subagent_spawn_count(args)
if self._session_subagent_count >= cap:
if self._turn_subagent_count >= cap:
decision = ToolGuardrailDecision(
action="block",
code="session_subagent_cap",
code="loop_subagent_cap",
message=(
f"Blocked delegate_task: this session has already spawned "
f"{self._session_subagent_count} subagents (limit {cap}). "
"This looks like a runaway delegation loop. Finish the work "
"with the results you have, or start a fresh session (/new) "
"to reset the budget."
f"Blocked delegate_task: this turn has already spawned "
f"{self._turn_subagent_count} subagents (limit {cap}). "
"This looks like a runaway delegation loop. Finish the "
"work with the results you have and answer the user."
),
tool_name=tool_name,
count=self._session_subagent_count,
count=self._turn_subagent_count,
signature=signature,
)
self._halt_decision = decision
return decision
self._session_subagent_count += spawn_count
self._turn_subagent_count += spawn_count
return None
return None

21
hermes_cli/config.py
View file

@ -1421,16 +1421,17 @@ DEFAULT_CONFIG = {
"same_tool_failure": 8,
"idempotent_no_progress": 5,
},
# Session-wide runaway-loop caps (inspired by Claude Code v2.1.212,
# Week 29, July 2026). Unlike the per-turn warn/hard-stop thresholds
# above, these count over the WHOLE session and reset only when a fresh
# session starts (/new or /clear). They are always-on hard ceilings — a
# legitimate session almost never issues 200 web searches or spawns 200
# subagents, so hitting one is a strong runaway-loop signal. Set either
# to 0 to disable that cap (unlimited).
"session_caps": {
"max_web_searches": 200, # max web_search calls per session (0 = unlimited)
"max_subagents": 200, # max subagents spawned per session (0 = unlimited)
# Per-turn runaway-loop caps (inspired by Claude Code v2.1.212,
# Week 29, July 2026). Hard ceilings on how many times a runaway-prone
# tool may be called within a SINGLE agent loop (turn); the counters
# reset at the start of every turn, so a legitimate multi-turn session
# is never starved. They are always-on and fire regardless of the
# warn/hard-stop thresholds above. A single turn issuing dozens of web
# searches or spawning dozens of subagents is already pathological, so
# the defaults are low. Set either to 0 to disable that cap (unlimited).
"loop_caps": {
"max_web_searches": 50, # max web_search calls per turn (0 = unlimited)
"max_subagents": 50, # max subagents spawned per turn (0 = unlimited)
},
},

74
tests/agent/test_tool_guardrails.py
View file

@ -279,65 +279,71 @@ def test_after_call_survives_lone_surrogates_in_result_and_args():
assert controller.before_call("web_search", {"query": dirty}).action == "block"
# ── Session-wide runaway-loop caps (Claude Code v2.1.212, Week 29) ──────────
# ── Per-turn runaway-loop caps (Claude Code v2.1.212, Week 29) ──────────────
from agent.tool_guardrails import SessionCapConfig # noqa: E402
from agent.tool_guardrails import LoopCapConfig # noqa: E402
def test_session_cap_defaults_match_claude_code():
caps = ToolCallGuardrailConfig().session_caps
assert caps.max_web_searches == 200
assert caps.max_subagents == 200
def test_loop_cap_defaults():
caps = ToolCallGuardrailConfig().loop_caps
assert caps.max_web_searches == 50
assert caps.max_subagents == 50
def test_session_cap_config_parses_nested_section():
def test_loop_cap_config_parses_nested_section():
cfg = ToolCallGuardrailConfig.from_mapping(
{"session_caps": {"max_web_searches": 3, "max_subagents": 0}}
{"loop_caps": {"max_web_searches": 3, "max_subagents": 0}}
)
assert cfg.session_caps.max_web_searches == 3
assert cfg.session_caps.max_subagents == 0
assert cfg.loop_caps.max_web_searches == 3
assert cfg.loop_caps.max_subagents == 0
def test_session_cap_zero_disables_and_junk_falls_back():
def test_loop_cap_zero_disables_and_junk_falls_back():
# 0 is a legitimate "unlimited" value; negatives / junk fall back to default.
assert SessionCapConfig.from_mapping({"max_web_searches": 0}).max_web_searches == 0
assert SessionCapConfig.from_mapping({"max_web_searches": -5}).max_web_searches == 200
assert SessionCapConfig.from_mapping({"max_subagents": "nope"}).max_subagents == 200
assert LoopCapConfig.from_mapping({"max_web_searches": 0}).max_web_searches == 0
assert LoopCapConfig.from_mapping({"max_web_searches": -5}).max_web_searches == 50
assert LoopCapConfig.from_mapping({"max_subagents": "nope"}).max_subagents == 50
def test_web_search_cap_blocks_after_limit_regardless_of_hard_stop():
# Session caps fire even with hard_stop_enabled=False (the per-turn loop
# Loop caps fire even with hard_stop_enabled=False (the per-turn loop
# detector's flag). Each distinct query avoids the loop detector so we know
# the block came from the session cap, not exact-failure repetition.
# the block came from the loop cap, not exact-failure repetition.
controller = ToolCallGuardrailController(
ToolCallGuardrailConfig(
hard_stop_enabled=False,
session_caps=SessionCapConfig(max_web_searches=3),
loop_caps=LoopCapConfig(max_web_searches=3),
)
)
for i in range(3):
assert controller.before_call("web_search", {"query": f"q{i}"}).action == "allow"
decision = controller.before_call("web_search", {"query": "q4"})
assert decision.action == "block"
assert decision.code == "session_web_search_cap"
assert decision.code == "loop_web_search_cap"
assert decision.should_halt is True
def test_web_search_cap_persists_across_turn_resets():
def test_web_search_cap_resets_each_turn():
# The cap bounds a single turn: reset_for_turn clears the counter so a
# legitimate multi-turn session is never starved.
controller = ToolCallGuardrailController(
ToolCallGuardrailConfig(session_caps=SessionCapConfig(max_web_searches=2))
ToolCallGuardrailConfig(loop_caps=LoopCapConfig(max_web_searches=2))
)
# Turn 1: two searches allowed, the third would block within the turn.
assert controller.before_call("web_search", {"query": "a"}).action == "allow"
controller.reset_for_turn() # a per-turn reset must NOT clear the session count
assert controller.before_call("web_search", {"query": "b"}).action == "allow"
controller.reset_for_turn()
assert controller.before_call("web_search", {"query": "c"}).action == "block"
# New turn: the counter resets, so the budget is fresh again.
controller.reset_for_turn()
assert controller.before_call("web_search", {"query": "d"}).action == "allow"
assert controller.before_call("web_search", {"query": "e"}).action == "allow"
assert controller.before_call("web_search", {"query": "f"}).action == "block"
def test_subagent_cap_counts_batch_task_spawns():
# A single delegate_task batch of N tasks spends N of the subagent budget.
controller = ToolCallGuardrailController(
ToolCallGuardrailConfig(session_caps=SessionCapConfig(max_subagents=5))
ToolCallGuardrailConfig(loop_caps=LoopCapConfig(max_subagents=5))
)
# First call spawns 3 (batch) → count 3, allowed.
assert controller.before_call(
@ -350,23 +356,33 @@ def test_subagent_cap_counts_batch_task_spawns():
# Now count is 5 (>= 5) so the next call is blocked.
decision = controller.before_call("delegate_task", {"goal": "f"})
assert decision.action == "block"
assert decision.code == "session_subagent_cap"
assert decision.code == "loop_subagent_cap"
def test_session_caps_disabled_when_zero():
def test_subagent_cap_resets_each_turn():
controller = ToolCallGuardrailController(
ToolCallGuardrailConfig(loop_caps=LoopCapConfig(max_subagents=1))
)
assert controller.before_call("delegate_task", {"goal": "a"}).action == "allow"
assert controller.before_call("delegate_task", {"goal": "b"}).action == "block"
controller.reset_for_turn()
assert controller.before_call("delegate_task", {"goal": "c"}).action == "allow"
def test_loop_caps_disabled_when_zero():
controller = ToolCallGuardrailController(
ToolCallGuardrailConfig(
session_caps=SessionCapConfig(max_web_searches=0, max_subagents=0)
loop_caps=LoopCapConfig(max_web_searches=0, max_subagents=0)
)
)
for i in range(50):
for i in range(60):
assert controller.before_call("web_search", {"query": f"q{i}"}).action == "allow"
assert controller.before_call("delegate_task", {"goal": f"g{i}"}).action == "allow"
def test_other_tools_never_touched_by_session_caps():
def test_other_tools_never_touched_by_loop_caps():
controller = ToolCallGuardrailController(
ToolCallGuardrailConfig(session_caps=SessionCapConfig(max_web_searches=1))
ToolCallGuardrailConfig(loop_caps=LoopCapConfig(max_web_searches=1))
)
# read_file / terminal / etc. are unaffected regardless of the web cap.
for _ in range(10):

10
website/docs/user-guide/configuration.md
View file

@ -1455,16 +1455,16 @@ tool_loop_guardrails:
exact_failure: 5
same_tool_failure: 8
idempotent_no_progress: 5
session_caps:
max_web_searches: 200 # max web_search calls per session (0 = unlimited)
max_subagents: 200 # max subagents spawned per session (0 = unlimited)
loop_caps:
max_web_searches: 50 # max web_search calls per turn (0 = unlimited)
max_subagents: 50 # max subagents spawned per turn (0 = unlimited)
```
`hard_stop_enabled` defaults to `false` because interactive sessions have a human in the loop. In unattended deployments (gateway, cron, kanban workers) set it to `true` so repeated failures are blocked rather than only warned. See also [Docker / unattended deployments](docker.md).
### Session-wide runaway-loop caps
### Per-turn runaway-loop caps
Separate from the per-turn thresholds above, `session_caps` sets hard ceilings on the total number of `web_search` calls and subagent spawns over the **whole session** (not per turn). These are always on — a legitimate session almost never issues 200 web searches or spawns 200 subagents, so hitting a cap is a strong runaway-loop signal. When a cap is reached, the offending tool call is blocked with an explanatory message and the turn stops cleanly instead of burning the rest of the budget. The counters reset only when a fresh session starts (`/new` or `/clear`). Set either value to `0` to disable that cap entirely.
Separate from the failure-based thresholds above, `loop_caps` sets hard ceilings on how many `web_search` calls and subagent spawns a single agent loop (turn) may make. The counters reset at the start of every turn, so a legitimate multi-turn session is never starved — but a single turn that spirals into an unbounded search or delegation loop is stopped. These are always on and fire regardless of `hard_stop_enabled`. A single turn issuing dozens of web searches or spawning dozens of subagents is already pathological, so the defaults are low. When a cap is reached, the offending tool call is blocked with an explanatory message and the turn stops cleanly instead of burning the rest of the budget. Set either value to `0` to disable that cap entirely.
A single `delegate_task` batch counts each task toward `max_subagents` (a batch of 3 spends 3), so the cap tracks real subagents spawned rather than `delegate_task` invocations.