feat(agent): iteration-cap recovery and ablation support

- when the tool budget is exhausted, force one final tools-disabled call
  so the agent answers from gathered evidence instead of giving up
- exclude_tools param on the agent/MCP client hides chosen tools
- THINKMCP_DISABLE_REASONING=1 hides think/critique/plan at the server
- correct search_code docs: GitHub code search requires auth

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: Gh-Novel

agent/mcp_client.py

@@ -30,9 +30,15 @@ class MCPToolClient:
             out = await mcp.call_tool("web_search_tool", {"query": "..."})
     """
 
-    def __init__(self, server_path: str = SERVER_PATH, env: dict[str, str] | None = None):
+    def __init__(
+        self,
+        server_path: str = SERVER_PATH,
+        env: dict[str, str] | None = None,
+        exclude_tools: set[str] | None = None,
+    ):
         self._server_path = server_path
         self._env = {**os.environ, **(env or {})}
+        self._exclude_tools = exclude_tools or set()
         self._stack: AsyncExitStack | None = None
         self.session: ClientSession | None = None
         self.tools: list[Any] = []
@@ -50,7 +56,7 @@ async def __aenter__(self) -> "MCPToolClient":
         await self.session.initialize()
 
         listing = await self.session.list_tools()
-        self.tools = listing.tools
+        self.tools = [t for t in listing.tools if t.name not in self._exclude_tools]
         self.ollama_tools = [
             {
                 "type": "function",

agent/thinking_agent.py

@@ -85,6 +85,7 @@ async def run_thinking_agent_async(
     on_event: Callable[[str, Any], None] | None = None,
     model: str = DEFAULT_MODEL,
     ollama_host: str = DEFAULT_OLLAMA_HOST,
+    exclude_tools: set[str] | None = None,
 ) -> tuple[str, list[dict]]:
     """
     Run the ThinkMCP agent on a query.
@@ -97,6 +98,7 @@ async def run_thinking_agent_async(
                   event_type in {'thinking', 'tool_call', 'tool_result', 'text', 'done'}
         model: Ollama model name (any tool-capable Qwen 3 variant works).
         ollama_host: Base URL of the Ollama server.
+        exclude_tools: Tool names to hide from the model (used for ablations).
 
     Returns:
         (final_answer, thinking_trace) where thinking_trace is a list of dicts
@@ -119,7 +121,7 @@ def _emit(event_type: str, data: Any) -> None:
             except Exception:
                 pass
 
-    async with MCPToolClient() as mcp:
+    async with MCPToolClient(exclude_tools=exclude_tools) as mcp:
         messages: list[dict] = [
             {"role": "system", "content": system},
             {"role": "user", "content": query},
@@ -183,6 +185,36 @@ def _emit(event_type: str, data: Any) -> None:
                     {"role": "tool", "tool_name": name, "content": result_str}
                 )
 
+        # Iteration cap reached — don't discard the gathered evidence.
+        # One final call with tools disabled forces an answer from context.
+        messages.append({
+            "role": "user",
+            "content": (
+                "You have reached the tool-call limit. Using only the "
+                "information gathered above, give your best final answer "
+                "now. Do not request any more tools."
+            ),
+        })
+        try:
+            response = await client.chat(
+                model=model,
+                messages=messages,
+                think=use_native_thinking,
+                options={"num_ctx": NUM_CTX},
+            )
+            msg = response.message
+            native_thought = getattr(msg, "thinking", None) or ""
+            tag_thought, visible = _split_think_tags(msg.content or "")
+            thought = native_thought or tag_thought
+            if thought.strip():
+                entry = _thinking_entry(step, thought.strip())
+                thinking_trace.append(entry)
+                _emit("thinking", entry)
+                step += 1
+            final_answer = visible.strip()
+        except ResponseError:
+            final_answer = ""
+
     final_answer = (
         final_answer
         or "Reached maximum iterations before the model produced a final answer."
@@ -198,6 +230,7 @@ def run_thinking_agent(
     on_event: Callable[[str, Any], None] | None = None,
     model: str = DEFAULT_MODEL,
     ollama_host: str = DEFAULT_OLLAMA_HOST,
+    exclude_tools: set[str] | None = None,
 ) -> tuple[str, list[dict]]:
     """Synchronous wrapper around run_thinking_agent_async."""
     return asyncio.run(
@@ -208,5 +241,6 @@ def run_thinking_agent(
             on_event=on_event,
             model=model,
             ollama_host=ollama_host,
+            exclude_tools=exclude_tools,
         )
     )

server/mcp_server.py

@@ -65,48 +65,50 @@ def search_papers_tool(topic: str) -> dict:
 def search_code_tool(query: str) -> dict:
     """
     Search GitHub for code matching a query.
-    Optionally uses GITHUB_TOKEN env var for higher rate limits.
+    Requires GITHUB_TOKEN (GitHub's code-search API needs auth; zero scopes suffice).
     Returns: {query, total_count, results: [{name, path, repo, url, score}]}
     """
     return search_code(query)
 
 
 # ── REASONING TOOLS ───────────────────────────────────────────────────────────
-
-@mcp.tool()
-def think_tool(thought: str) -> str:
-    """
-    A scratchpad for mid-workflow reasoning. Use this between tool calls to:
-    - Plan next steps
-    - Evaluate quality of retrieved results
-    - Detect contradictions between sources
-    - Decide if more information is needed
-    Does NOT call any external service. Returns the thought for traceability.
-    """
-    return think(thought)
-
-
-@mcp.tool()
-def critique_tool(answer: str, question: str) -> dict:
-    """
-    Self-evaluate a draft answer before returning it to the user.
-    Returns a structured quality assessment with confidence score,
-    missing aspects, and a recommendation to accept or revise.
-    Returns: {answer_preview, word_count, completeness, confidence,
-              missing_aspects, recommendation}
-    """
-    return critique(answer, question)
-
-
-@mcp.tool()
-def plan_tool(goal: str) -> dict:
-    """
-    Break a goal into an ordered list of actionable sub-steps.
-    Detects goal type (research, comparison, implementation, summarization)
-    and returns a tailored strategy.
-    Returns: {goal, strategy, steps: [...], total_steps}
-    """
-    return plan(goal)
+# THINKMCP_DISABLE_REASONING=1 hides these three tools entirely — used by the
+# benchmark's ablated arm so the model cannot see (not just cannot call) them.
+
+if os.environ.get("THINKMCP_DISABLE_REASONING", "") != "1":
+
+    @mcp.tool()
+    def think_tool(thought: str) -> str:
+        """
+        A scratchpad for mid-workflow reasoning. Use this between tool calls to:
+        - Plan next steps
+        - Evaluate quality of retrieved results
+        - Detect contradictions between sources
+        - Decide if more information is needed
+        Does NOT call any external service. Returns the thought for traceability.
+        """
+        return think(thought)
+
+    @mcp.tool()
+    def critique_tool(answer: str, question: str) -> dict:
+        """
+        Self-evaluate a draft answer before returning it to the user.
+        Returns a structured quality assessment with confidence score,
+        missing aspects, and a recommendation to accept or revise.
+        Returns: {answer_preview, word_count, completeness, confidence,
+                  missing_aspects, recommendation}
+        """
+        return critique(answer, question)
+
+    @mcp.tool()
+    def plan_tool(goal: str) -> dict:
+        """
+        Break a goal into an ordered list of actionable sub-steps.
+        Detects goal type (research, comparison, implementation, summarization)
+        and returns a tailored strategy.
+        Returns: {goal, strategy, steps: [...], total_steps}
+        """
+        return plan(goal)
 
 
 # ── MEMORY TOOLS ──────────────────────────────────────────────────────────────