fix: add stagnation_detector to loop docstrings, strengthen turn assertion

Aureliolo · Aureliolo · commit f24b1cfc2541 · 2026-03-15T20:21:28.000+01:00
- Add stagnation_detector to PlanExecuteLoop and ReactLoop Args docstrings
- Strengthen STAGNATION turn count assertion: verify both planning and
  tool-use turns are present (not just &gt;= 1)
diff --git a/src/synthorg/engine/plan_execute_loop.py b/src/synthorg/engine/plan_execute_loop.py
@@ -91,6 +91,10 @@ class PlanExecuteLoop:
         approval_gate: Optional gate that checks for pending escalations
             after tool execution and parks the agent when approval is
             required.  ``None`` disables approval checks.
+        stagnation_detector: Optional detector that checks for
+            repetitive tool-call patterns within each step and
+            intervenes with corrective prompts or early termination.
+            ``None`` disables stagnation detection.
     """
 
     def __init__(
diff --git a/src/synthorg/engine/react_loop.py b/src/synthorg/engine/react_loop.py
@@ -71,6 +71,10 @@ class ReactLoop:
         approval_gate: Optional gate that checks for pending escalations
             after tool execution and parks the agent when approval is
             required.  ``None`` disables approval checks.
+        stagnation_detector: Optional detector that checks for
+            repetitive tool-call patterns and intervenes with
+            corrective prompts or early termination.  ``None``
+            disables stagnation detection.
     """
 
     def __init__(
diff --git a/tests/unit/engine/test_plan_execute_loop.py b/tests/unit/engine/test_plan_execute_loop.py
@@ -923,8 +923,11 @@ async def test_stagnation_within_step_triggers_terminate(
 
         assert result.termination_reason == TerminationReason.STAGNATION
         assert "stagnation" in result.metadata
-        # STAGNATION result must include ALL turns, not just step-scoped
-        assert len(result.turns) >= 1
+        # STAGNATION result must include ALL turns (planning + tool-use),
+        # not just step-scoped turns.
+        assert len(result.turns) == 2
+        assert result.turns[0].tool_calls_made == ()  # planning turn
+        assert result.turns[1].tool_calls_made == ("echo",)  # tool turn
 
     async def test_stagnation_correction_in_step(
         self,
