doc + refactor: address remaining PR review threads

README.md: Add the per-task backend override as the highest-precedence
selection level. Tasks can put 'backend:' in their own model_settings
block to override the model-level value, per _resolve_task_model().

doc/GRAMMAR.md: Tighten the 'passed through to the selected SDK backend'
claim. openai_agents accepts the standard OpenAI parameter set,
anthropic_sdk forwards a curated subset (temperature, top_p, reasoning,
max_tokens, stream_thinking), and copilot_sdk consumes only its own
exposed keys (e.g. reasoning_effort) and silently ignores the rest.
Avoid misleading users about arbitrary key forwarding.

mcp_utils.py: Make list_tools_unfiltered idempotent on the prefix.
Strip an existing namespace prefix before re-applying so the method
is safe to call repeatedly even if the underlying session somehow
returns a cached/reused tool object whose name was previously
namespaced. Uses str.removeprefix() (no-op when prefix is absent).

Regression test added covering the previously-prefixed-input path.
276 tests pass, hatch fmt clean.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: anticomputer

README.md

@@ -103,13 +103,16 @@ The runner can drive three SDKs behind a common interface:
   Designed for use with CAPI's Anthropic endpoint; auth uses
   `Authorization: Bearer` (not `x-api-key`).
 
-Selection precedence:
-
-1. Per-model `backend:` in `model_settings` (allows mixed backends in a
-   single taskflow).
-2. `backend:` field in the model config document (global default).
-3. `SECLAB_TASKFLOW_BACKEND` environment variable.
-4. `openai_agents`.
+Selection precedence (highest to lowest):
+
+1. Per-task `backend:` in the task's own `model_settings` block (overrides
+   the model-level value for that one task; see `_resolve_task_model()`).
+2. Per-model `backend:` in the model config's `model_settings` (allows
+   mixed backends in a single taskflow).
+3. `backend:` field at the top level of the model config document
+   (global default).
+4. `SECLAB_TASKFLOW_BACKEND` environment variable.
+5. `openai_agents`.
 
 ```yaml
 seclab-taskflow-agent:

doc/GRAMMAR.md

@@ -550,5 +550,10 @@ passed to the underlying model provider:
 | `endpoint` | API base URL for this model | The global `AI_API_ENDPOINT` env var |
 | `token` | Name of an environment variable containing the API key | Uses `AI_API_TOKEN` / `COPILOT_TOKEN` |
 
-All other keys (e.g. `temperature`, `top_p`, `reasoning`) are passed through as
-model parameters to the selected SDK backend.
+All other keys (e.g. `temperature`, `top_p`, `reasoning`) are forwarded to
+the selected SDK backend. Which keys are actually honored depends on the
+backend: `openai_agents` accepts the standard OpenAI parameter set;
+`anthropic_sdk` forwards a curated subset (currently `temperature`,
+`top_p`, `reasoning`, `max_tokens`, `stream_thinking`); `copilot_sdk`
+consumes only the keys its SDK exposes (e.g. `reasoning_effort`) and
+silently ignores the rest. Consult the backend-specific docs if in doubt.

src/seclab_taskflow_agent/mcp_utils.py

@@ -106,6 +106,12 @@ async def list_tools_unfiltered(self) -> list[Any]:
         run loop -- e.g. when handing tools to a different SDK at build
         time).
 
+        Prefixing is idempotent: if a tool's name already starts with this
+        wrapper's namespace (e.g. because the underlying session returned a
+        previously-namespaced object), the existing prefix is stripped
+        before re-applying so calling this method multiple times never
+        yields ``<ns><ns>name``.
+
         Raises ``RuntimeError`` if the underlying server has no active
         MCP session yet (caller should ensure the server is connected
         before calling this).
@@ -120,7 +126,9 @@ async def list_tools_unfiltered(self) -> list[Any]:
         namespaced_tools: list[Any] = []
         for tool in result.tools:
             tool_copy = tool.copy() if hasattr(tool, "copy") else tool
-            tool_copy.name = f"{self.namespace}{tool.name}"
+            # Idempotent: strip existing prefix before re-applying
+            base_name = tool_copy.name.removeprefix(self.namespace)
+            tool_copy.name = f"{self.namespace}{base_name}"
             namespaced_tools.append(tool_copy)
         return namespaced_tools
 

tests/test_mcp_utils.py

@@ -111,6 +111,23 @@ def test_list_tools_unfiltered_does_not_share_state_with_caller():
     assert original.name == "read_file"
 
 
+def test_list_tools_unfiltered_idempotent_on_prefixed_input():
+    """If the session returns a tool whose name is already namespace-prefixed
+    (e.g. because of a cached/reused tool object), the prefix must NOT be
+    applied a second time. Required for safe repeated/reentrant calls."""
+    ns = compress_name("RepoContext")
+    pre_prefixed = _FakeTool(f"{ns}read_file", "Read a file")
+    session = MagicMock()
+    session.list_tools = AsyncMock(return_value=SimpleNamespace(tools=[pre_prefixed]))
+    wrapper = _make_wrapper("RepoContext", session=session)
+
+    result = asyncio.run(wrapper.list_tools_unfiltered())
+
+    # Result must have exactly one prefix, not two
+    assert result[0].name == f"{ns}read_file"
+    assert not result[0].name.startswith(f"{ns}{ns}")
+
+
 # -- list_tools() (regression) --