fix(llm): recover empty tool-loop responses instead of returning null

When the model returns an empty response with no tool calls, the tool
loop's empty-response retry only fires when iterations remain
(`iteration < max_tool_iterations - 1`). At the dialectic `minimal` tier
(MAX_TOOL_ITERATIONS=1) that guard is `0 < 0 == False`, so the retry can
never fire and the tool-less branch returns empty content without
reaching the post-loop synthesis call. The empty string then surfaces as
a null dialectic response (the chat endpoint maps a falsy answer to
None), so broad `minimal` queries returned null even though the same
query answered correctly at `low`/`medium`.

Decouple empty-response recovery from the iteration budget: keep the
nudge-and-loop when iterations remain, otherwise break to the forced
synthesis call so a final answer is always produced. This is a general
tool-loop correctness fix; `minimal` is where it is guaranteed to
surface. The synthesis prompt and log now distinguish empty-recovery
from genuine max-iteration exhaustion.

Adds a deterministic regression test covering the single-iteration
recovery path and the multi-iteration control.

Author: leo.lc.chien

src/llm/tool_loop.py

@@ -404,6 +404,10 @@ async def execute_tool_loop(
     # DialecticCompletedEvent.hit_input_token_cap reflect the cap hit
     # (the toolless path tracks this in src/llm/api.py:325-340).
     hit_input_token_cap = False
+    # Set when an empty tool-less response can't be retried in-loop (no
+    # iterations left) and we break out to the forced synthesis call to
+    # recover a final answer instead of returning empty.
+    empty_recovery_synthesis = False
     # Track effective tool_choice — switches from "required"/"any" to "auto" after iter 1.
     effective_tool_choice = tool_choice
 
@@ -492,24 +496,34 @@ async def _call_with_messages(
             if not response.tool_calls_made:
                 logger.debug("No tool calls in response, finishing")
 
-                if (
-                    isinstance(response.content, str)
-                    and not response.content.strip()
-                    and empty_response_retries < 1
-                    and iteration < max_tool_iterations - 1
-                ):
+                is_empty_response = (
+                    isinstance(response.content, str) and not response.content.strip()
+                )
+                if is_empty_response and empty_response_retries < 1:
                     empty_response_retries += 1
-                    conversation_messages.append(
-                        {
-                            "role": "user",
-                            "content": (
-                                "Your last response was empty. Provide a concise answer "
-                                "to the original query using the available context."
-                            ),
-                        }
-                    )
-                    iteration += 1
-                    continue
+                    if iteration < max_tool_iterations - 1:
+                        # Budget remains: nudge the model and loop again.
+                        conversation_messages.append(
+                            {
+                                "role": "user",
+                                "content": (
+                                    "Your last response was empty. Provide a concise answer "
+                                    "to the original query using the available context."
+                                ),
+                            }
+                        )
+                        iteration += 1
+                        continue
+                    if not stream_final:
+                        # No iterations left to loop — notably the minimal tier
+                        # (max_tool_iterations=1), where `iteration < max_tool_iterations - 1`
+                        # is `0 < 0 == False` so the nudge above can never fire.
+                        # Break out to the forced synthesis call after the loop
+                        # rather than returning an empty/null answer. Without
+                        # this, the empty-response safety net silently no-ops for
+                        # single-iteration levels.
+                        empty_recovery_synthesis = True
+                        break
 
                 if stream_final:
                     # Snapshot the plan that just succeeded — streaming retries
@@ -657,19 +671,27 @@ async def _call_with_messages(
 
         iteration += 1
 
-    logger.warning(
-        f"Tool execution loop reached max iterations ({max_tool_iterations})"
-    )
+    if empty_recovery_synthesis:
+        logger.debug("Empty tool-less response, no retries left; forcing synthesis")
+        synthesis_prompt = (
+            "Your previous response was empty. Using the context already available, "
+            "provide your final answer to the original query now. "
+            "Do not attempt to call any tools."
+        )
+    else:
+        logger.warning(
+            f"Tool execution loop reached max iterations ({max_tool_iterations})"
+        )
+        synthesis_prompt = (
+            "You have reached the maximum number of tool calls. "
+            "Based on all the information you have gathered, provide your final response now. "
+            "Do not attempt to call any more tools."
+        )
 
-    # The max-iteration synthesis call gets iteration N+1 in telemetry so 's
+    # The synthesis call gets iteration N+1 in telemetry so 's
     # AgentIterationEvent and this LLMCallCompletedEvent line up sequentially.
     synthesis_iteration = iteration + 1
 
-    synthesis_prompt = (
-        "You have reached the maximum number of tool calls. "
-        "Based on all the information you have gathered, provide your final response now. "
-        "Do not attempt to call any more tools."
-    )
     conversation_messages.append({"role": "user", "content": synthesis_prompt})
 
     # Truncate again — the per-iteration truncate ran before the last tool

tests/llm/test_dialectic_minimal_empty_recovery.py

@@ -0,0 +1,143 @@
+# pyright: reportPrivateUsage=false, reportUnknownLambdaType=false, reportUnknownArgumentType=false, reportArgumentType=false
+"""Isolation tests for empty-final-response recovery in `execute_tool_loop`.
+
+Proves — independent of any deployment, stored data, or LLM nondeterminism —
+that when the model returns an *empty* final answer with no tool calls, the
+loop's recovery depends on the iteration budget in a way that silently breaks
+the `minimal` dialectic tier (`MAX_TOOL_ITERATIONS=1`).
+
+The empty-response retry in `tool_loop.py` is gated on
+`iteration < max_tool_iterations - 1`. At `max_tool_iterations=1` that is
+`0 < 0` = False, so the ONLY empty-response safety net never fires and there
+is no synthesis fallback on the no-tool path → the loop returns an empty
+(null) answer. With `max_tool_iterations>=2` the retry fires and recovers.
+
+`test_empty_final_response_recovered_at_single_iteration` FAILS on unfixed
+code (returns "") and passes once the recovery is decoupled from the
+iteration budget. The `..._with_budget` control passes on both, isolating the
+defect to the single-iteration case.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import pytest
+
+from src.llm import tool_loop
+from src.llm.runtime import AttemptPlan
+from src.llm.tool_loop import execute_tool_loop
+from src.llm.types import HonchoLLMCallResponse
+
+
+def _make_plan() -> AttemptPlan:
+    """Return a minimal AttemptPlan the mocked inner call passes straight through."""
+    return AttemptPlan(
+        provider="anthropic",
+        model="claude-sonnet-4-5",
+        client=object(),
+        thinking_budget_tokens=None,
+        reasoning_effort=None,
+        selected_config=None,
+        attempt=1,
+        retry_attempts=1,
+        is_fallback=False,
+    )
+
+
+def _resp(content: str) -> HonchoLLMCallResponse[Any]:
+    """Build a no-tool-call LLM response carrying the given content."""
+    return HonchoLLMCallResponse(
+        content=content,
+        input_tokens=10,
+        output_tokens=5,
+        cache_creation_input_tokens=0,
+        cache_read_input_tokens=0,
+        finish_reasons=["stop"],
+        tool_calls_made=[],
+    )
+
+
+class _EmptyThenRecover:
+    """Mock inner-LLM: the first tool-enabled call returns empty content with
+    no tool calls (the failure the model actually produces at `minimal` on
+    broad recall queries). Recovery paths return distinct sentinels so the
+    test can tell HOW recovery happened:
+      - `tools=None`  → forced synthesis call  → "recovered via synthesis"
+      - 2nd tool call → nudge-and-loop retry   → "recovered via retry"
+    """
+
+    def __init__(self) -> None:
+        """Initialize per-call counters for tool-enabled and synthesis calls."""
+        self.tool_enabled_calls = 0
+        self.synthesis_calls = 0
+
+    async def __call__(self, *_args: Any, **kwargs: Any) -> HonchoLLMCallResponse[Any]:
+        """Return empty then recovery content, keyed off whether tools are passed."""
+        if kwargs.get("tools") is None:  # forced final synthesis call
+            self.synthesis_calls += 1
+            return _resp("recovered via synthesis")
+        self.tool_enabled_calls += 1
+        if self.tool_enabled_calls == 1:
+            return _resp("")  # empty final answer, no tool calls
+        return _resp("recovered via retry")
+
+
+_TOOLS = [{"name": "noop", "description": "no-op", "input_schema": {"type": "object"}}]
+
+
+async def _run(max_tool_iterations: int, mock: _EmptyThenRecover) -> Any:
+    """Drive execute_tool_loop with the mock at the given iteration budget."""
+    return await execute_tool_loop(
+        prompt="hi",
+        max_tokens=250,
+        messages=[{"role": "user", "content": "What do you know about me?"}],
+        tools=_TOOLS,
+        tool_choice="auto",
+        tool_executor=lambda _name, _input: "",
+        max_tool_iterations=max_tool_iterations,
+        response_model=None,
+        json_mode=False,
+        temperature=None,
+        stop_seqs=None,
+        verbosity=None,
+        enable_retry=False,
+        retry_attempts=1,
+        max_input_tokens=None,
+        get_attempt_plan=_make_plan,
+        before_retry_callback=lambda _r: None,
+        stream_final=False,
+        telemetry=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_empty_final_response_recovered_at_single_iteration():
+    """minimal tier (`max_tool_iterations=1`): an empty no-tool answer must be
+    recovered, not returned as null. FAILS on unfixed code (returns "")."""
+    mock = _EmptyThenRecover()
+    with pytest.MonkeyPatch.context() as mp:
+        mp.setattr(tool_loop, "honcho_llm_call_inner", mock)
+        result = await _run(1, mock)
+
+    assert isinstance(result, HonchoLLMCallResponse)
+    assert result.content and result.content.strip(), (
+        f"minimal tier returned an empty/null answer: {result.content!r}"
+    )
+    assert result.content == "recovered via synthesis"
+    assert mock.synthesis_calls == 1
+
+
+@pytest.mark.asyncio
+async def test_empty_final_response_recovered_with_budget():
+    """Control: with `max_tool_iterations=2` the existing nudge-and-loop retry
+    already recovers. Passes on both unfixed and fixed code, isolating the
+    defect to the single-iteration case."""
+    mock = _EmptyThenRecover()
+    with pytest.MonkeyPatch.context() as mp:
+        mp.setattr(tool_loop, "honcho_llm_call_inner", mock)
+        result = await _run(2, mock)
+
+    assert isinstance(result, HonchoLLMCallResponse)
+    assert result.content == "recovered via retry"
+    assert mock.tool_enabled_calls == 2