fix(agents): collapse repeated waits queued inside one model turn (#979)

* fix(agents): collapse repeated waits queued inside one model turn

* fix(agents): state that one wait is enough in every prompt variant

---------

Co-authored-by: Ahmed Allam <ahmed39652003@gmail.com>

strix/agents/prompts/system_prompt.jinja

@@ -28,6 +28,7 @@ INTER-AGENT MESSAGES:
 - Messages from other agents arrive prefixed with a header like `[Message from agent <name> | type=... | priority=...]`. Treat them as internal context — never repeat them verbatim in your own output.
 - Treat agent identity / inherited-context preambles as internal metadata; do not echo them in outputs or tool calls.
 - Minimize inter-agent messaging: only message when essential for coordination or assistance; avoid routine status updates; batch non-urgent information; prefer parent/child completion flows and shared artifacts over messaging
+- wait_for_agents blocks and resumes you automatically, so it is never a poll you repeat: issue exactly ONE wait, then stop and react to what it returns. Never write out a wait/check loop (wait → view_agent_graph → wait → ...) ahead of time — those extra calls only strand you and are collapsed anyway
 
 {% if interactive %}
 INTERACTIVE BEHAVIOR:

strix/core/hooks.py

@@ -20,6 +20,8 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 
+LLM_TURN_KEY = "llm_turn"
+
 _STAGE_LABELS: tuple[str, ...] = ("NOTICE", "URGENT", "CRITICAL")
 _TURN_WARN_BANDS: tuple[float, ...] = (0.70, 0.85, 0.95)
 _ROOT_BUDGET_WARN_BANDS: tuple[float, ...] = (0.70, 0.85, 0.95)
@@ -144,6 +146,7 @@ class ReportUsageHooks(RunHooks[dict[str, Any]]):
         system_prompt: str | None,  # noqa: ARG002
         input_items: list[TResponseInputItem],
     ) -> None:
+        context.context[LLM_TURN_KEY] = int(context.context.get(LLM_TURN_KEY, 0)) + 1
         try:
             self._maybe_warn_turns(context, input_items)
             self._maybe_warn_budget(context, input_items)

strix/tools/agents_graph/tools.py

@@ -14,6 +14,7 @@ from agents import RunContextWrapper, function_tool
 
 from strix.core.agents import Status, coordinator_from_context
 from strix.core.execution import notify_parent_on_terminal
+from strix.core.hooks import LLM_TURN_KEY
 from strix.skills import validate_requested_skills
 
 
@@ -224,6 +225,7 @@ _WAIT_DEFAULT_TIMEOUT_S = 300
 # ``timeout_seconds`` the model asks for. One second of headroom lets the
 # tool's own timeout fire first and return a clean result.
 _WAIT_HARD_CEILING_S = _WAIT_DEFAULT_TIMEOUT_S + 1
+_WAITED_TURN_KEY = "waited_llm_turn"
 
 
 @function_tool(timeout=_WAIT_HARD_CEILING_S)
@@ -239,6 +241,11 @@ async def wait_for_agents(  # noqa: PLR0911
     completion reports. You resume the instant any message arrives, so
     size ``timeout_seconds`` to the work you're awaiting.
 
+    **Issue exactly one wait, then stop and react to what it returns.**
+    This call blocks and resumes on its own; it is not a poll you repeat.
+    Do not write out a wait/check loop ahead of time — a second wait in
+    the same turn returns immediately without waiting.
+
     **This tool is only for waiting on other agents.** Two things it is
     NOT for:
 
@@ -290,6 +297,24 @@ async def wait_for_agents(  # noqa: PLR0911
             default=str,
         )
 
+    turn = inner.get(LLM_TURN_KEY)
+    if turn is not None and inner.get(_WAITED_TURN_KEY) == turn:
+        return json.dumps(
+            {
+                "success": True,
+                "wait_outcome": "already_waited",
+                "reason": reason,
+                "note": (
+                    "You already waited in this turn. A single wait_for_agents blocks and "
+                    "resumes on its own, so queueing more waits only strands you — issue one "
+                    "wait, then react to what it returns."
+                ),
+            },
+            ensure_ascii=False,
+            default=str,
+        )
+    inner[_WAITED_TURN_KEY] = turn
+
     async with coordinator._lock:
         stopped = coordinator.statuses.get(me) == "stopped"
     if stopped: