@miller-tech/uap 1.76.5 → 1.77.0

package/tools/agents/scripts/anthropic_proxy.py

@@ -189,6 +189,23 @@ PROXY_TOOL_STATE_FINALIZE_THRESHOLD = int(
 PROXY_TOOL_STATE_REVIEW_CYCLE_LIMIT = int(
     os.environ.get("PROXY_TOOL_STATE_REVIEW_CYCLE_LIMIT", "3")
 )
+# #4 Coordination no-op suppression. Pure-bookkeeping tools (task/board status
+# updates) are never productive to repeat, so they are banned after fewer cycle
+# detections than the generic per-tool threshold. This targets the 35B-A3B
+# "update the task instead of doing the actual work" loop (observed live:
+# cycling_tools=['TaskUpdate']). Tunable via env; set the threshold to 0 to
+# disable the faster ban and fall back to the generic threshold.
+PROXY_COORDINATION_TOOLS = {
+    t.strip()
+    for t in os.environ.get(
+        "PROXY_COORDINATION_TOOLS",
+        "TaskUpdate,TaskCreate,TaskList,TaskGet,TaskOutput",
+    ).split(",")
+    if t.strip()
+}
+PROXY_COORDINATION_BAN_THRESHOLD = int(
+    os.environ.get("PROXY_COORDINATION_BAN_THRESHOLD", "2")
+)
 # Force finalize after N consecutive forced_budget_exhausted events where
 # neither cycling nor stagnation was detected — catches "distinct but
 # unproductive" tool spam that defeats per-tool cycle detection.
@@ -498,6 +515,20 @@ PROXY_FORCE_NON_STREAM = os.environ.get(
     "off",
     "no",
 }
+# Streaming keep-alive heartbeat (seconds) for the guarded-non-stream path.
+# That path buffers the ENTIRE upstream generation before emitting any SSE
+# bytes, so a long generation (e.g. a 28k-token runaway taking ~14 min at
+# depth-slowed decode) sends the client nothing for the whole wait and the
+# client's streaming idle-timeout fires -> "API Error". When > 0, the proxy
+# emits an immediate `message_start` then periodic `ping` events to the client
+# while it awaits+guards the buffered upstream response, keeping the connection
+# alive; the buffered content is streamed once ready. 0 disables (old behavior).
+try:
+    PROXY_STREAM_HEARTBEAT_SECS = float(
+        os.environ.get("PROXY_STREAM_HEARTBEAT_SECS", "0")
+    )
+except ValueError:
+    PROXY_STREAM_HEARTBEAT_SECS = 0.0
 PROXY_FORCED_TOOL_DAMPENER = os.environ.get(
     "PROXY_FORCED_TOOL_DAMPENER", "on"
 ).lower() not in {
@@ -3648,15 +3679,26 @@ def _resolve_state_machine_tool_choice(
                 for part in fp.split("|"):
                     raw_names.append(part.split(":")[0])
             monitor.cycling_tool_names = list(dict.fromkeys(raw_names))
-            # Cycle 18 Option 2: track per-tool cycle counts and ban after 3 cycles
+            # Cycle 18 Option 2: track per-tool cycle counts and ban after N cycles.
+            # #4: coordination/bookkeeping tools (TaskUpdate etc.) are banned
+            # faster (PROXY_COORDINATION_BAN_THRESHOLD) since repeating them is
+            # never productive; other tools keep the generic threshold of 3.
             for name in monitor.cycling_tool_names:
                 monitor.tool_cycle_counts[name] = monitor.tool_cycle_counts.get(name, 0) + 1
-                if monitor.tool_cycle_counts[name] >= 3 and name not in monitor.session_banned_tools:
+                is_coord = (
+                    name in PROXY_COORDINATION_TOOLS
+                    and PROXY_COORDINATION_BAN_THRESHOLD > 0
+                )
+                ban_at = PROXY_COORDINATION_BAN_THRESHOLD if is_coord else 3
+                if monitor.tool_cycle_counts[name] >= ban_at and name not in monitor.session_banned_tools:
                     monitor.session_banned_tools.add(name)
                     logger.warning(
-                        "TOOL BAN: '%s' banned for session after %d cycle detections",
+                        "TOOL BAN: '%s' banned for session after %d cycle detections "
+                        "(threshold=%d%s)",
                         name,
                         monitor.tool_cycle_counts[name],
+                        ban_at,
+                        ", coordination" if is_coord else "",
                     )
             logger.warning(
                 "TOOL STATE MACHINE: entering review (cycle=%s repeat=%d stagnation=%d cycles=%d cycling_tools=%s)",
@@ -7838,19 +7880,84 @@ def openai_to_anthropic_response(
     }
 
 
-async def stream_anthropic_message(anthropic_resp: dict):
-    """Stream a finalized Anthropic message as SSE events."""
-    message = {
-        "id": anthropic_resp.get("id", f"msg_{uuid.uuid4().hex[:24]}"),
-        "type": "message",
-        "role": "assistant",
-        "content": [],
-        "model": anthropic_resp.get("model", "unknown"),
-        "stop_reason": None,
-        "stop_sequence": None,
-        "usage": {"input_tokens": 0, "output_tokens": 0},
-    }
-    yield f"event: message_start\ndata: {json.dumps({'type': 'message_start', 'message': message})}\n\n"
+async def _heartbeat_then_buffered(produce_coro, model: str):
+    """SSE generator: keep-alive heartbeat wrapper for the guarded-non-stream path.
+
+    Emits an immediate ``message_start`` so the client registers an active
+    stream, then ``ping`` events every PROXY_STREAM_HEARTBEAT_SECS while
+    ``produce_coro`` (which awaits + guards the buffered upstream response) runs,
+    then streams the buffered content. Keeps the connection alive through long
+    buffered generations so the client's streaming idle-timeout does not fire.
+
+    ``produce_coro`` resolves to EITHER the finalized Anthropic response dict OR
+    a Starlette ``Response`` (the guarded path's error returns). Since the stream
+    has already committed to HTTP 200, an error Response is re-emitted as an SSE
+    ``error`` event rather than an HTTP status.
+    """
+    msg_id = f"msg_{uuid.uuid4().hex[:24]}"
+    yield (
+        f"event: message_start\n"
+        f"data: {json.dumps({'type': 'message_start', 'message': {'id': msg_id, 'type': 'message', 'role': 'assistant', 'content': [], 'model': model, 'stop_reason': None, 'stop_sequence': None, 'usage': {'input_tokens': 0, 'output_tokens': 0}}})}\n\n"
+    )
+    interval = PROXY_STREAM_HEARTBEAT_SECS if PROXY_STREAM_HEARTBEAT_SECS > 0 else 15.0
+    task = asyncio.ensure_future(produce_coro)
+    try:
+        while True:
+            try:
+                # shield keeps the produce task alive across ping timeouts;
+                # only the wait_for wrapper is cancelled on each TimeoutError.
+                produced = await asyncio.wait_for(asyncio.shield(task), timeout=interval)
+                break
+            except asyncio.TimeoutError:
+                yield 'event: ping\ndata: {"type": "ping"}\n\n'
+    except asyncio.CancelledError:
+        # Client disconnected — cancel the in-flight produce and propagate.
+        task.cancel()
+        raise
+    except Exception as exc:
+        logger.error("heartbeat produce failed: %s", exc)
+        yield (
+            "event: error\n"
+            f"data: {json.dumps({'type': 'error', 'error': {'type': 'api_error', 'message': str(exc)[:500]}})}\n\n"
+        )
+        return
+
+    if isinstance(produced, Response):
+        # Guarded path returned an error Response; re-emit as an SSE error event.
+        try:
+            payload = json.loads(bytes(produced.body).decode("utf-8"))
+        except Exception:
+            payload = {
+                "type": "error",
+                "error": {"type": "overloaded_error", "message": "Upstream error"},
+            }
+        yield f"event: error\ndata: {json.dumps(payload)}\n\n"
+        return
+
+    # produced is the finalized Anthropic response dict — stream its content
+    # without a second message_start (already sent above).
+    async for chunk in stream_anthropic_message(produced, emit_message_start=False):
+        yield chunk
+
+
+async def stream_anthropic_message(anthropic_resp: dict, emit_message_start: bool = True):
+    """Stream a finalized Anthropic message as SSE events.
+
+    emit_message_start=False skips the leading message_start event for callers
+    (the heartbeat wrapper) that have already emitted one to start the stream.
+    """
+    if emit_message_start:
+        message = {
+            "id": anthropic_resp.get("id", f"msg_{uuid.uuid4().hex[:24]}"),
+            "type": "message",
+            "role": "assistant",
+            "content": [],
+            "model": anthropic_resp.get("model", "unknown"),
+            "stop_reason": None,
+            "stop_sequence": None,
+            "usage": {"input_tokens": 0, "output_tokens": 0},
+        }
+        yield f"event: message_start\ndata: {json.dumps({'type': 'message_start', 'message': message})}\n\n"
 
     content_blocks = anthropic_resp.get("content", []) or [{"type": "text", "text": ""}]
     block_index = 0
@@ -8528,88 +8635,108 @@ async def messages(request: Request):
         openai_body,
     )
     if use_guarded_non_stream:
-        strict_body = dict(openai_body)
-        strict_body["stream"] = False
+        async def _produce_guarded():
+            strict_body = dict(openai_body)
+            strict_body["stream"] = False
 
-        try:
-            strict_resp = await _post_with_generation_timeout(
-                client,
-                f"{LLAMA_CPP_BASE}/chat/completions",
-                strict_body,
-                {"Content-Type": "application/json"},
-            )
-        except Exception as exc:
-            # Check if upstream is hung before returning error
-            await _check_slot_hang(LLAMA_CPP_BASE.replace("/v1", "/slots"))
-            return Response(
-                content=json.dumps(
-                    {
-                        "type": "error",
-                        "error": {
-                            "type": "overloaded_error",
-                            "message": f"Upstream server unavailable after {PROXY_UPSTREAM_RETRY_MAX} retries: {exc}",
-                        },
-                    }
-                ),
-                status_code=529,
-                media_type="application/json",
-            )
+            try:
+                strict_resp = await _post_with_generation_timeout(
+                    client,
+                    f"{LLAMA_CPP_BASE}/chat/completions",
+                    strict_body,
+                    {"Content-Type": "application/json"},
+                )
+            except Exception as exc:
+                # Check if upstream is hung before returning error
+                await _check_slot_hang(LLAMA_CPP_BASE.replace("/v1", "/slots"))
+                return Response(
+                    content=json.dumps(
+                        {
+                            "type": "error",
+                            "error": {
+                                "type": "overloaded_error",
+                                "message": f"Upstream server unavailable after {PROXY_UPSTREAM_RETRY_MAX} retries: {exc}",
+                            },
+                        }
+                    ),
+                    status_code=529,
+                    media_type="application/json",
+                )
 
-        if strict_resp.status_code != 200:
-            error_text = strict_resp.text[:1000]
-            # Try the Gemma 4 PEG parse-failure recovery first — relax
-            # tool_choice='required' so the retry isn't constrained by the
-            # strict-grammar that triggered the parse failure.
-            relaxed = _is_gemma4_peg_parse_failure(strict_resp.status_code, error_text) and \
-                _relax_tool_choice_for_gemma4_peg_retry(strict_body, "strict-stream")
-            if relaxed:
-                try:
-                    strict_resp = await _post_with_generation_timeout(
-                        client,
-                        f"{LLAMA_CPP_BASE}/chat/completions",
-                        strict_body,
-                        {"Content-Type": "application/json"},
-                    )
-                except Exception:
-                    pass  # fall through to next handler
-        if strict_resp.status_code != 200:
-            error_text = strict_resp.text[:1000]
-            if _maybe_disable_grammar_for_tools_error(
-                strict_body,
-                strict_resp.status_code,
-                error_text,
-                "strict-stream",
-            ):
-                try:
-                    strict_resp = await _post_with_generation_timeout(
-                        client,
-                        f"{LLAMA_CPP_BASE}/chat/completions",
-                        strict_body,
-                        {"Content-Type": "application/json"},
+            if strict_resp.status_code != 200:
+                error_text = strict_resp.text[:1000]
+                # Try the Gemma 4 PEG parse-failure recovery first — relax
+                # tool_choice='required' so the retry isn't constrained by the
+                # strict-grammar that triggered the parse failure.
+                relaxed = _is_gemma4_peg_parse_failure(strict_resp.status_code, error_text) and \
+                    _relax_tool_choice_for_gemma4_peg_retry(strict_body, "strict-stream")
+                if relaxed:
+                    try:
+                        strict_resp = await _post_with_generation_timeout(
+                            client,
+                            f"{LLAMA_CPP_BASE}/chat/completions",
+                            strict_body,
+                            {"Content-Type": "application/json"},
+                        )
+                    except Exception:
+                        pass  # fall through to next handler
+            if strict_resp.status_code != 200:
+                error_text = strict_resp.text[:1000]
+                if _maybe_disable_grammar_for_tools_error(
+                    strict_body,
+                    strict_resp.status_code,
+                    error_text,
+                    "strict-stream",
+                ):
+                    try:
+                        strict_resp = await _post_with_generation_timeout(
+                            client,
+                            f"{LLAMA_CPP_BASE}/chat/completions",
+                            strict_body,
+                            {"Content-Type": "application/json"},
+                        )
+                    except Exception as exc:
+                        return Response(
+                            content=json.dumps(
+                                {
+                                    "type": "error",
+                                    "error": {
+                                        "type": "overloaded_error",
+                                        "message": f"Upstream server unavailable after {PROXY_UPSTREAM_RETRY_MAX} retries: {exc}",
+                                    },
+                                }
+                            ),
+                            status_code=529,
+                            media_type="application/json",
+                        )
+
+            if strict_resp.status_code != 200:
+                error_text = strict_resp.text[:1000]
+                # Cycle 19 Option 2: For 503 "Loading model", don't advance state
+                # machine — return retriable 503 with Retry-After header so the
+                # client can retry without wasting state machine budget.
+                if _is_loading_model_503(strict_resp):
+                    logger.warning(
+                        "Upstream 503 Loading model (strict-stream) — returning retriable 503 without advancing state",
                     )
-                except Exception as exc:
                     return Response(
                         content=json.dumps(
                             {
                                 "type": "error",
                                 "error": {
                                     "type": "overloaded_error",
-                                    "message": f"Upstream server unavailable after {PROXY_UPSTREAM_RETRY_MAX} retries: {exc}",
+                                    "message": "Upstream model is loading. Retry in 10 seconds.",
                                 },
                             }
                         ),
-                        status_code=529,
+                        status_code=503,
+                        headers={"Retry-After": "10"},
                         media_type="application/json",
                     )
-
-        if strict_resp.status_code != 200:
-            error_text = strict_resp.text[:1000]
-            # Cycle 19 Option 2: For 503 "Loading model", don't advance state
-            # machine — return retriable 503 with Retry-After header so the
-            # client can retry without wasting state machine budget.
-            if _is_loading_model_503(strict_resp):
-                logger.warning(
-                    "Upstream 503 Loading model (strict-stream) — returning retriable 503 without advancing state",
+                logger.error(
+                    "Upstream HTTP %d (strict-stream): %s",
+                    strict_resp.status_code,
+                    error_text,
                 )
                 return Response(
                     content=json.dumps(
@@ -8617,126 +8744,122 @@ async def messages(request: Request):
                             "type": "error",
                             "error": {
                                 "type": "overloaded_error",
-                                "message": "Upstream model is loading. Retry in 10 seconds.",
+                                "message": f"Upstream error (HTTP {strict_resp.status_code}): {error_text[:500]}",
                             },
                         }
                     ),
-                    status_code=503,
-                    headers={"Retry-After": "10"},
+                    status_code=529,
                     media_type="application/json",
                 )
-            logger.error(
-                "Upstream HTTP %d (strict-stream): %s",
-                strict_resp.status_code,
-                error_text,
+
+            openai_resp = strict_resp.json()
+            # Recover tool calls from <tool_call> XML before guardrails run
+            _maybe_extract_text_tool_calls(
+                openai_resp,
+                anthropic_tools=body.get("tools"),
+                suppress=monitor.suppress_text_tool_extraction,
             )
-            return Response(
-                content=json.dumps(
-                    {
-                        "type": "error",
-                        "error": {
-                            "type": "overloaded_error",
-                            "message": f"Upstream error (HTTP {strict_resp.status_code}): {error_text[:500]}",
-                        },
-                    }
-                ),
-                status_code=529,
-                media_type="application/json",
+            openai_resp = await _apply_unexpected_end_turn_guardrail(
+                client,
+                openai_resp,
+                strict_body,
+                body,
+                monitor,
+                session_id,
+            )
+            openai_resp = await _apply_malformed_tool_guardrail(
+                client,
+                openai_resp,
+                strict_body,
+                body,
+                monitor,
+                session_id,
             )
 
-        openai_resp = strict_resp.json()
-        # Recover tool calls from <tool_call> XML before guardrails run
-        _maybe_extract_text_tool_calls(
-            openai_resp,
-            anthropic_tools=body.get("tools"),
-            suppress=monitor.suppress_text_tool_extraction,
-        )
-        openai_resp = await _apply_unexpected_end_turn_guardrail(
-            client,
-            openai_resp,
-            strict_body,
-            body,
-            monitor,
-            session_id,
-        )
-        openai_resp = await _apply_malformed_tool_guardrail(
-            client,
-            openai_resp,
-            strict_body,
-            body,
-            monitor,
-            session_id,
-        )
-
-        openai_resp, was_degenerate = _detect_and_truncate_degenerate_repetition(openai_resp)
-        if was_degenerate:
-            # Retry with constrained parameters to avoid degenerate output.
-            # With tools: force tool_choice=required for a useful tool call.
-            # Without tools (finalize): retry with capped max_tokens for clean text.
-            has_tools = bool(strict_body.get("tools"))
-            retry_body = dict(strict_body)
-            retry_body["max_tokens"] = 2048
-            retry_body["temperature"] = 0.1
-            retry_body["stream"] = False
-            if has_tools:
-                retry_body["tool_choice"] = "required"
-                logger.warning("DEGENERATE RETRY: retrying with tool_choice=required max_tokens=2048")
+            openai_resp, was_degenerate = _detect_and_truncate_degenerate_repetition(openai_resp)
+            if was_degenerate:
+                # Retry with constrained parameters to avoid degenerate output.
+                # With tools: force tool_choice=required for a useful tool call.
+                # Without tools (finalize): retry with capped max_tokens for clean text.
+                has_tools = bool(strict_body.get("tools"))
+                retry_body = dict(strict_body)
+                retry_body["max_tokens"] = 2048
+                retry_body["temperature"] = 0.1
+                retry_body["stream"] = False
+                if has_tools:
+                    retry_body["tool_choice"] = "required"
+                    logger.warning("DEGENERATE RETRY: retrying with tool_choice=required max_tokens=2048")
+                else:
+                    logger.warning("DEGENERATE RETRY: retrying text-only with max_tokens=2048 temp=0.1")
+                try:
+                    retry_resp = await _post_with_generation_timeout(
+                        client, f"{LLAMA_CPP_BASE}/chat/completions", retry_body,
+                        {"Content-Type": "application/json"},
+                    )
+                    if retry_resp.status_code == 200:
+                        retry_data = retry_resp.json()
+                        retry_text = _openai_message_text(retry_data)
+                        _, retry_degenerate = _detect_and_truncate_degenerate_repetition(retry_data)
+                        if retry_degenerate:
+                            logger.info("DEGENERATE RETRY: retry also degenerate, using truncated original")
+                        elif has_tools and (retry_data.get("choices", [{}])[0]
+                                .get("message", {}).get("tool_calls")):
+                            logger.info("DEGENERATE RETRY: success, got tool call")
+                            openai_resp = retry_data
+                        elif not has_tools and retry_text and len(retry_text) > 50:
+                            logger.info("DEGENERATE RETRY: success, got clean text (%d chars)", len(retry_text))
+                            openai_resp = retry_data
+                        else:
+                            logger.info("DEGENERATE RETRY: retry insufficient, using truncated original")
+                except Exception as exc:
+                    logger.warning("DEGENERATE RETRY: failed: %s", exc)
+            anthropic_resp = openai_to_anthropic_response(
+                openai_resp, model,
+                expose_thinking=isinstance(body.get("thinking"), dict)
+                    and (body["thinking"].get("type") or "").lower() == "enabled",
+                suppress_text_tool_extraction=monitor.suppress_text_tool_extraction,
+            )
+            _maybe_normalize_toolcall_paths(anthropic_resp, body)
+            # FINALIZE CONTINUATION: inject synthetic tool_use to keep client loop alive
+            if (
+                monitor.finalize_turn_active
+                and monitor.finalize_continuation_count < PROXY_FINALIZE_CONTINUATION_MAX
+                and anthropic_resp.get("stop_reason") == "end_turn"
+            ):
+                anthropic_resp = _inject_synthetic_continuation(anthropic_resp, monitor, body)
+            monitor.record_response(anthropic_resp.get("usage", {}).get("output_tokens", 0))
+            # Update last_input_tokens from upstream's actual prompt_tokens
+            upstream_input = anthropic_resp.get("usage", {}).get("input_tokens", 0)
+            if upstream_input > 0:
+                monitor.last_input_tokens = upstream_input
+            if PROXY_FORCE_NON_STREAM:
+                logger.info(
+                    "FORCED NON-STREAM: served stream response via guarded non-stream path"
+                )
+            elif PROXY_MALFORMED_TOOL_STREAM_STRICT and _has_tool_definitions(body):
+                logger.info(
+                    "STRICT STREAM GUARDRAIL: served stream response via guarded non-stream path"
+                )
             else:
-                logger.warning("DEGENERATE RETRY: retrying text-only with max_tokens=2048 temp=0.1")
-            try:
-                retry_resp = await _post_with_generation_timeout(
-                    client, f"{LLAMA_CPP_BASE}/chat/completions", retry_body,
-                    {"Content-Type": "application/json"},
+                logger.info(
+                    "REQUIRED TOOL STREAM GUARDRAIL: served stream response via guarded non-stream path"
                 )
-                if retry_resp.status_code == 200:
-                    retry_data = retry_resp.json()
-                    retry_text = _openai_message_text(retry_data)
-                    _, retry_degenerate = _detect_and_truncate_degenerate_repetition(retry_data)
-                    if retry_degenerate:
-                        logger.info("DEGENERATE RETRY: retry also degenerate, using truncated original")
-                    elif has_tools and (retry_data.get("choices", [{}])[0]
-                            .get("message", {}).get("tool_calls")):
-                        logger.info("DEGENERATE RETRY: success, got tool call")
-                        openai_resp = retry_data
-                    elif not has_tools and retry_text and len(retry_text) > 50:
-                        logger.info("DEGENERATE RETRY: success, got clean text (%d chars)", len(retry_text))
-                        openai_resp = retry_data
-                    else:
-                        logger.info("DEGENERATE RETRY: retry insufficient, using truncated original")
-            except Exception as exc:
-                logger.warning("DEGENERATE RETRY: failed: %s", exc)
-        anthropic_resp = openai_to_anthropic_response(
-            openai_resp, model,
-            expose_thinking=isinstance(body.get("thinking"), dict)
-                and (body["thinking"].get("type") or "").lower() == "enabled",
-            suppress_text_tool_extraction=monitor.suppress_text_tool_extraction,
-        )
-        _maybe_normalize_toolcall_paths(anthropic_resp, body)
-        # FINALIZE CONTINUATION: inject synthetic tool_use to keep client loop alive
-        if (
-            monitor.finalize_turn_active
-            and monitor.finalize_continuation_count < PROXY_FINALIZE_CONTINUATION_MAX
-            and anthropic_resp.get("stop_reason") == "end_turn"
-        ):
-            anthropic_resp = _inject_synthetic_continuation(anthropic_resp, monitor, body)
-        monitor.record_response(anthropic_resp.get("usage", {}).get("output_tokens", 0))
-        # Update last_input_tokens from upstream's actual prompt_tokens
-        upstream_input = anthropic_resp.get("usage", {}).get("input_tokens", 0)
-        if upstream_input > 0:
-            monitor.last_input_tokens = upstream_input
-        if PROXY_FORCE_NON_STREAM:
-            logger.info(
-                "FORCED NON-STREAM: served stream response via guarded non-stream path"
-            )
-        elif PROXY_MALFORMED_TOOL_STREAM_STRICT and _has_tool_definitions(body):
-            logger.info(
-                "STRICT STREAM GUARDRAIL: served stream response via guarded non-stream path"
-            )
-        else:
-            logger.info(
-                "REQUIRED TOOL STREAM GUARDRAIL: served stream response via guarded non-stream path"
-            )
 
+            return anthropic_resp
+
+        if PROXY_STREAM_HEARTBEAT_SECS > 0:
+            return StreamingResponse(
+                _heartbeat_then_buffered(_produce_guarded(), model),
+                media_type="text/event-stream",
+                headers={
+                    "Cache-Control": "no-cache",
+                    "Connection": "keep-alive",
+                },
+            )
+        _produced = await _produce_guarded()
+        if isinstance(_produced, Response):
+            return _produced
+        anthropic_resp = _produced
         return StreamingResponse(
             stream_anthropic_message(anthropic_resp),
             media_type="text/event-stream",

package/tools/agents/tests/test_coordination_ban.py

@@ -0,0 +1,68 @@
+"""Tests for #4: coordination-tool no-op loop suppression (faster ban).
+
+A pure-bookkeeping tool that cycles (e.g. TaskUpdate) is banned after
+PROXY_COORDINATION_BAN_THRESHOLD (2) cycle detections, while a generic tool
+keeps the original threshold of 3. Banning removes the tool from the offered
+set, physically breaking the "update the task instead of doing the work" loop.
+"""
+import importlib.util
+import unittest
+from pathlib import Path
+
+proxy_path = Path(__file__).resolve().parents[1] / "scripts" / "anthropic_proxy.py"
+spec = importlib.util.spec_from_file_location("anthropic_proxy", proxy_path)
+ap = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(ap)
+
+
+def _cycling_body(tool="TaskUpdate"):
+    # >= PROXY_TOOL_STATE_MIN_MESSAGES (6) messages, last user message carries a
+    # tool_result -> active agentic loop.
+    msgs = [{"role": "user", "content": "do the task"}]
+    for i in range(3):
+        msgs.append({"role": "assistant", "content": [
+            {"type": "tool_use", "id": f"t{i}", "name": tool, "input": {}}]})
+        msgs.append({"role": "user", "content": [
+            {"type": "tool_result", "tool_use_id": f"t{i}", "content": "ok"}]})
+    return {"messages": msgs}
+
+
+def _drive_one_cycle(monitor, tool):
+    """Put the monitor in act-phase with a detected cycle of `tool` and run the
+    state-machine resolver once (which runs the ban loop)."""
+    fp = f"{tool}:deadbeef"
+    monitor.tool_turn_phase = "act"
+    monitor.tool_state_forced_budget_remaining = 5
+    monitor.tool_state_review_cycles = 0
+    win = max(2, ap.PROXY_TOOL_STATE_CYCLE_WINDOW)
+    monitor.tool_call_history = [fp] * (win + 2)
+    monitor.last_tool_fingerprint = fp
+    monitor.tool_state_stagnation_streak = max(1, ap.PROXY_TOOL_STATE_STAGNATION_THRESHOLD)
+    ap._resolve_state_machine_tool_choice(
+        _cycling_body(tool), monitor, has_tool_results=True, last_user_has_tool_result=True
+    )
+
+
+class CoordinationBanTest(unittest.TestCase):
+    def test_config_defaults(self):
+        self.assertIn("TaskUpdate", ap.PROXY_COORDINATION_TOOLS)
+        self.assertEqual(ap.PROXY_COORDINATION_BAN_THRESHOLD, 2)
+
+    def test_coordination_tool_banned_after_two_cycles(self):
+        m = ap.SessionMonitor(context_window=132096)
+        _drive_one_cycle(m, "TaskUpdate")
+        self.assertNotIn("TaskUpdate", m.session_banned_tools, "should not ban after 1 cycle")
+        _drive_one_cycle(m, "TaskUpdate")
+        self.assertIn("TaskUpdate", m.session_banned_tools, "should ban after 2 cycles (coordination)")
+
+    def test_generic_tool_needs_three_cycles(self):
+        m = ap.SessionMonitor(context_window=132096)
+        for _ in range(2):
+            _drive_one_cycle(m, "glob")
+        self.assertNotIn("glob", m.session_banned_tools, "generic tool must NOT ban at 2")
+        _drive_one_cycle(m, "glob")
+        self.assertIn("glob", m.session_banned_tools, "generic tool bans at 3")
+
+
+if __name__ == "__main__":
+    unittest.main()