docs(skills): verify release status and behavior per assessment

* feat(mcp): initialize connections lazily

* fix(mcp): replace terminally dead sessions

* fix(mcp): improve targeted tool discovery

* fix(mcp): limit active tool fallback

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install dev-install format lint type-check security check-all clean pre-commit setup-dev dev viewer wheel tui-build tui-test tui-lint
+.PHONY: help install dev-install format lint format-check lint-check type-check security check-all clean pre-commit setup-dev dev viewer wheel tui-build tui-test tui-lint
 
 TUI_BINARY := build/sidecar/strix-tui$(if $(filter Windows_NT,$(OS)),.exe)
 
@@ -10,7 +10,9 @@ help:
 	@echo ""
 	@echo "Code Quality:"
 	@echo "  format        - Format code with ruff"
-	@echo "  lint          - Lint code with ruff"
+	@echo "  lint          - Lint code with ruff and apply fixes"
+	@echo "  format-check  - Check formatting without modifying files"
+	@echo "  lint-check    - Check lint without modifying files"
 	@echo "  type-check    - Run type checking with mypy and pyright"
 	@echo "  security      - Run security checks with bandit"
 	@echo "  check-all     - Run all code quality checks"
@@ -45,6 +47,12 @@ lint:
 	uv run ruff check . --fix
 	@echo "✅ Linting complete!"
 
+format-check:
+	uv run ruff format --check .
+
+lint-check:
+	uv run ruff check .
+
 type-check:
 	@echo "🔍 Type checking with mypy..."
 	uv run mypy strix/
@@ -57,7 +65,7 @@ security:
 	uv run bandit -r strix/ -c pyproject.toml
 	@echo "✅ Security checks complete!"
 
-check-all: format lint type-check security
+check-all: format-check lint-check type-check security
 	@echo "✅ All code quality checks passed!"
 
 pre-commit:

pyproject.toml

@@ -308,6 +308,9 @@ ignore = [
 "strix/report/dedupe.py" = ["PLC0415"]
 "strix/telemetry/logging.py" = ["PLC0415"]
 "strix/config/models.py" = ["PLC0415"]
+# LiteLLM is imported lazily: the request log is wired at startup on every
+# route, including the native OpenAI ones that never load LiteLLM.
+"strix/llm/request_log.py" = ["PLC0415"]
 # Heavy inference deps (httpx, openai) imported lazily so auth-status checks
 # don't pull them in.
 "strix/config/codex.py" = ["PLC0415"]

strix/agents/factory.py

@@ -29,7 +29,13 @@ from strix.tools.agents_graph.tools import (
 from strix.tools.coverage.tools import list_coverage, record_coverage, update_coverage
 from strix.tools.finish.tool import finish_scan
 from strix.tools.load_skill.tool import load_skill
-from strix.tools.mcp import call_mcp, describe_mcp, list_mcps
+from strix.tools.mcp import (
+    call_mcp,
+    describe_mcp,
+    get_mcp_tool_schema,
+    list_mcps,
+    search_mcp_tools,
+)
 from strix.tools.notes.tools import (
     create_note,
     delete_note,
@@ -594,6 +600,8 @@ _BASE_TOOLS: tuple[Tool, ...] = (
     view_sitemap_entry,
     scope_rules,
     list_mcps,
+    search_mcp_tools,
+    get_mcp_tool_schema,
     describe_mcp,
     call_mcp,
     view_agent_graph,

strix/agents/prompts/system_prompt.jinja

@@ -77,18 +77,20 @@ AUTHORIZED TARGETS:
 
 {% if system_prompt_context and system_prompt_context.mcp_available %}
 MCP CONNECTIONS (available this run):
-- The user connected one or more MCP (Model Context Protocol) servers — external tool providers you can reach on demand. Their individual tools do NOT appear in your tool list; three dispatch tools are the only way in.
+- The user connected one or more MCP (Model Context Protocol) servers. Their individual tools do NOT appear in your tool list. Use the four discovery and dispatch tools to reach them.
 {% if system_prompt_context.mcp_connections %}
-- Connected this run (call describe_mcp on one to see its tools):
+- Connected this run (search one to find relevant tools):
 {% for connection in system_prompt_context.mcp_connections %}
   - {{ connection.name }} ({{ connection.tool_count }} tools){% if connection.purpose %}: {{ connection.purpose }}{% endif %}
 {% endfor %}
 {% endif %}
 - Reach for a connection whenever the target itself cannot give you information a connection could: its database schema and access policies, real deployment or infrastructure configuration, known issues or prior findings, or server logs. In those cases call list_mcps early to see what is available, and prefer a connection's authoritative data over inferring from the target's responses. Do not wait to be told a connection exists.
   1. Call list_mcps() to discover the available connections.
-  2. Call describe_mcp(connection="<name>") to inspect one connection's tools, each with its name, description, and JSON input schema.
-  3. Call call_mcp(connection="<name>", tool="<tool>", arguments={...}) to run one, passing an arguments object that matches the schema (omit arguments for a tool that takes none).
-- Do not assume a connection or tool exists; discover it with list_mcps and describe it with describe_mcp before calling.
+  2. Call search_mcp_tools(connection="<name>", query="<capability>") for a short candidate list.
+  3. Call get_mcp_tool_schema(connection="<name>", tool="<tool>") for the one schema you need.
+  4. Call call_mcp(connection="<name>", tool="<tool>", arguments={...}) to run it, passing an arguments object that matches the schema (omit arguments for a tool that takes none).
+- Do not assume a connection or tool exists; discover it with list_mcps and search_mcp_tools before calling.
+- Use describe_mcp only as a compatibility fallback when targeted search cannot identify an expected tool. Its full catalog can be large.
 {% endif %}
 
 AUTHORIZATION STATUS:

strix/config/codex.py

@@ -356,6 +356,8 @@ def build_openai_client() -> AsyncOpenAI:
     import httpx
     from openai import AsyncOpenAI
 
+    from strix.llm import request_log
+
     get_valid_token()  # fail fast at configure time if the sign-in is dead
 
     async def _auth_hook(request: httpx.Request) -> None:
@@ -367,6 +369,7 @@ def build_openai_client() -> AsyncOpenAI:
         timeout=httpx.Timeout(600.0, connect=30.0),
         event_hooks={"request": [_auth_hook]},
     )
+    request_log.observe_http_client(http_client)
     return AsyncOpenAI(
         api_key="strix-codex-oauth",  # placeholder; the hook overwrites Authorization
         base_url=CODEX_BASE_URL,

strix/config/models.py

@@ -40,6 +40,7 @@ from strix.config import codex
 from strix.config.loader import load_settings
 from strix.config.tool_call_ids import TurnCallIdRewriter, dedupe_input
 from strix.config.tool_call_limits import TurnToolCallLimiter
+from strix.llm import request_log
 
 
 if TYPE_CHECKING:
@@ -390,7 +391,7 @@ def _guard_event(
     event: TResponseStreamEvent, rewriter: TurnCallIdRewriter, limiter: TurnToolCallLimiter
 ) -> TResponseStreamEvent | None:
     if isinstance(event, ResponseOutputItemAddedEvent | ResponseOutputItemDoneEvent):
-        rewritten = rewriter.rewrite_item(event.item)
+        rewritten = rewriter.rewrite_item(event.item, event.output_index)
         if not limiter.allow(rewritten):
             return None
         if rewritten is not event.item:
@@ -525,13 +526,37 @@ class StrixProvider(MultiProvider):
             # The ChatGPT subscription backend is always streamed; it has no
             # non-streaming mode to fall back to, so LLM_DISABLE_STREAMING
             # does not apply here.
-            model: Model = _CodexResponsesModel(
-                slug,
-                codex.get_subscription_client(),
-                reasoning_effort=llm.reasoning_effort,
+            model: Model = request_log.RequestLoggingModel(
+                _CodexResponsesModel(
+                    slug,
+                    codex.get_subscription_client(),
+                    reasoning_effort=llm.reasoning_effort,
+                ),
+                model_name=slug,
+                provider="openai-codex",
+                base_url=None,
             )
         else:
             model = super().get_model(model_name)
+            resolved_name = model_name or llm.model or "unknown"
+            if _routes_via_litellm(model):
+                # LiteLLM's callbacks log every reply; only a cancelled attempt
+                # (stream idle timeout, abandoned turn) escapes them.
+                model = request_log.RequestLoggingModel(
+                    model,
+                    model_name=resolved_name,
+                    provider=_litellm_provider(resolved_name),
+                    base_url=self._override_base_url or llm.api_base,
+                    route="litellm",
+                    abandoned_only=True,
+                )
+            else:
+                model = request_log.RequestLoggingModel(
+                    model,
+                    model_name=resolved_name,
+                    provider="openai",
+                    base_url=self._override_base_url or llm.api_base,
+                )
             if llm.disable_streaming:
                 model = _NonStreamingModel(model)
                 # The wrapper emits its single event only once the whole request
@@ -545,6 +570,23 @@ class StrixProvider(MultiProvider):
         )
 
 
+def _routes_via_litellm(model: Model) -> bool:
+    """LiteLLM-backed models are captured by the LiteLLM callback, not the wrapper."""
+    from agents.extensions.models.litellm_model import LitellmModel
+
+    return isinstance(model, LitellmModel)
+
+
+def _litellm_provider(model_name: str) -> str | None:
+    """The provider LiteLLM will route ``model_name`` to, if it can tell."""
+    try:
+        import litellm
+
+        return str(litellm.get_llm_provider(model_name)[1])
+    except Exception:  # noqa: BLE001 - unknown model ids are the provider's problem, not the log's
+        return None
+
+
 DEFAULT_MODEL_RETRY = ModelRetrySettings(
     max_retries=5,
     backoff=ModelRetryBackoffSettings(
@@ -621,6 +663,7 @@ def configure_sdk_model_defaults(settings: Settings) -> None:
     """Apply Strix config to SDK-native defaults."""
     llm = settings.llm
     set_tracing_disabled(True)
+    request_log.install()
     if codex.subscription_model(llm.model):
         return
     _configure_litellm_compatibility()
@@ -773,12 +816,16 @@ def _merge_litellm_headers(headers: dict[str, str]) -> None:
 
 def _register_openai_client_with_headers(llm: LlmSettings, headers: dict[str, str]) -> None:
     from agents import set_default_openai_client
+    from agents.models.openai_provider import shared_http_client
     from openai import AsyncOpenAI
 
     client = AsyncOpenAI(
         api_key=llm.api_key or "not-needed",
         base_url=llm.api_base,
         default_headers=dict(headers),
+        # The SDK's shared client is the one the request log observes for
+        # reply status, headers and provider request ids.
+        http_client=shared_http_client(),
     )
     set_default_openai_client(client, use_for_tracing=False)
 

strix/config/tool_call_ids.py

@@ -1,12 +1,17 @@
-"""Keep tool-call ids unique within a conversation.
+"""Keep tool-call ids present and unique within a conversation.
 
 Some providers return per-turn tool-call ids (``exec_command:0``,
 ``exec_command:1``, ...) whose counter restarts on every turn. Once the same
 id appears twice in one conversation, the request payload has two assistant
 tool calls sharing an id and strict providers reject the whole turn, which
 permanently kills the agent because the malformed history is replayed on
-every retry. Rewriting duplicates to fresh unique ids keeps the history
-valid for any provider.
+every retry.
+
+Others omit the id altogether, or return it as an empty string. That turns
+the paired tool result into a ``tool`` message with an empty
+``tool_call_id``, which strict providers reject the same way and with the
+same permanent outcome. Rewriting both blank and duplicate ids to fresh
+unique ones keeps the history valid for any provider.
 """
 
 from __future__ import annotations
@@ -15,6 +20,7 @@ from collections import defaultdict, deque
 from typing import Any
 from uuid import uuid4
 
+from agents.models.fake_id import FAKE_RESPONSES_ID
 from openai.types.responses import ResponseFunctionToolCall
 
 
@@ -22,23 +28,29 @@ def new_call_id() -> str:
     return f"call_{uuid4().hex}"
 
 
+def _pairing_key(call_id: Any) -> str:
+    """Bucket an id for call/output pairing; all blank ids share one bucket."""
+    return call_id if isinstance(call_id, str) else ""
+
+
 def collect_call_ids(items: list[Any]) -> set[str]:
     used: set[str] = set()
     for item in items:
         if isinstance(item, dict):
             call_id = item.get("call_id")
-            if isinstance(call_id, str):
+            if isinstance(call_id, str) and call_id:
                 used.add(call_id)
-        elif isinstance(item, ResponseFunctionToolCall):
+        elif isinstance(item, ResponseFunctionToolCall) and item.call_id:
             used.add(item.call_id)
     return used
 
 
 def dedupe_history_call_ids(items: list[Any]) -> tuple[list[Any], bool]:
-    """Rewrite duplicate call ids in a conversation history.
+    """Rewrite blank and duplicate call ids in a conversation history.
 
     Outputs are paired with their call by order, so parallel calls that share
-    an id keep answering the right call after the rewrite.
+    an id — or are all missing one — keep answering the right call after the
+    rewrite.
     """
     used: set[str] = set()
     pending: dict[str, deque[str]] = defaultdict(deque)
@@ -49,22 +61,24 @@ def dedupe_history_call_ids(items: list[Any]) -> tuple[list[Any], bool]:
         if not isinstance(item, dict):
             rebuilt.append(item)
             continue
-        call_id = item.get("call_id")
-        if not isinstance(call_id, str):
+
+        kind = item.get("type")
+        if kind not in ("function_call", "function_call_output"):
             rebuilt.append(item)
             continue
 
-        kind = item.get("type")
+        call_id = item.get("call_id")
+        key = _pairing_key(call_id)
         if kind == "function_call":
-            effective = call_id
-            if call_id in used:
+            effective = key
+            if not effective or effective in used:
                 effective = new_call_id()
                 item = {**item, "call_id": effective}  # noqa: PLW2901
                 changed = True
             used.add(effective)
-            pending[call_id].append(effective)
-        elif kind == "function_call_output":
-            queue = pending.get(call_id)
+            pending[key].append(effective)
+        else:
+            queue = pending.get(key)
             if queue:
                 effective = queue.popleft()
                 if effective != call_id:
@@ -83,7 +97,7 @@ def dedupe_input(model_input: str | list[Any]) -> str | list[Any]:
 
 
 class TurnCallIdRewriter:
-    """Rewrite a single turn's tool-call ids that collide with the history.
+    """Rewrite a single turn's tool-call ids that are blank or collide with the history.
 
     A turn's items surface several times (streamed item events, then the
     completed response), so the same original id must always map to the same
@@ -93,12 +107,37 @@ class TurnCallIdRewriter:
     def __init__(self, model_input: str | list[Any]) -> None:
         self._used = set() if isinstance(model_input, str) else collect_call_ids(model_input)
         self._remap: dict[str, str] = {}
+        self._blank_remap: dict[str, str] = {}
         self._settled: set[str] = set()
 
-    def rewrite_item(self, item: Any) -> Any:
+    def _rewrite_blank(
+        self, item: ResponseFunctionToolCall, position: int | None
+    ) -> ResponseFunctionToolCall:
+        """Give a call with no id one that stays the same on every sighting.
+
+        A real item id tells parallel calls apart. Chat Completions routes give
+        every item the same placeholder id, so there the call's position in
+        the turn's output tells them apart instead.
+        """
+        if item.id and item.id != FAKE_RESPONSES_ID:
+            key = item.id
+        else:
+            key = f"{FAKE_RESPONSES_ID}#{position}"
+        replacement = self._blank_remap.get(key)
+        if replacement is None:
+            replacement = new_call_id()
+            self._blank_remap[key] = replacement
+            self._used.add(replacement)
+            self._settled.add(replacement)
+        return item.model_copy(update={"call_id": replacement})
+
+    def rewrite_item(self, item: Any, position: int | None = None) -> Any:
+        """Rewrite one item; ``position`` is its index in the turn's output."""
         if not isinstance(item, ResponseFunctionToolCall):
             return item
         original = item.call_id
+        if not original:
+            return self._rewrite_blank(item, position)
         if original in self._settled:
             return item
         replacement = self._remap.get(original)
@@ -114,4 +153,4 @@ class TurnCallIdRewriter:
         return item.model_copy(update={"call_id": replacement})
 
     def rewrite_items(self, items: list[Any]) -> list[Any]:
-        return [self.rewrite_item(item) for item in items]
+        return [self.rewrite_item(item, position) for position, item in enumerate(items)]

strix/core/execution.py

@@ -33,6 +33,7 @@ from strix.core.sessions import (
     seed_initial_input,
     strip_all_images_from_session,
 )
+from strix.llm import request_log
 from strix.llm.compaction import is_context_overflow, maybe_compact
 
 
@@ -197,6 +198,44 @@ async def run_agent_loop(
     start_parked: bool = False,
     event_sink: StreamEventSink | None = None,
     hooks: RunHooks[dict[str, Any]] | None = None,
+) -> RunResultBase | None:
+    agent_name = getattr(agent, "name", None)
+    token = request_log.bind_call_context(
+        agent_id, agent_name if isinstance(agent_name, str) else None
+    )
+    try:
+        return await _run_agent_loop(
+            agent=agent,
+            initial_input=initial_input,
+            run_config=run_config,
+            context=context,
+            max_turns=max_turns,
+            coordinator=coordinator,
+            agent_id=agent_id,
+            interactive=interactive,
+            session=session,
+            start_parked=start_parked,
+            event_sink=event_sink,
+            hooks=hooks,
+        )
+    finally:
+        request_log.reset_call_context(token)
+
+
+async def _run_agent_loop(
+    *,
+    agent: Any,
+    initial_input: Any,
+    run_config: RunConfig,
+    context: dict[str, Any],
+    max_turns: int,
+    coordinator: AgentCoordinator,
+    agent_id: str,
+    interactive: bool,
+    session: Session | None,
+    start_parked: bool,
+    event_sink: StreamEventSink | None,
+    hooks: RunHooks[dict[str, Any]] | None,
 ) -> RunResultBase | None:
     await coordinator.attach_runtime(
         agent_id,
@@ -636,7 +675,7 @@ async def _run_cycle_parked(
         raise
     except Exception as exc:
         logger.exception("error escaped the run cycle for %s; parking as failed", agent_id)
-        await coordinator.set_status(agent_id, "failed", error=str(exc) or type(exc).__name__)
+        await coordinator.set_status(agent_id, "failed", error=request_log.failure_text(exc))
         await notify_parent_on_terminal(coordinator, agent_id, "failed")
         return None
 
@@ -658,6 +697,7 @@ async def _run_cycle(  # noqa: PLR0912, PLR0915
     image_strips = 0
     compactions = 0
     model_retries = 0
+    request_log.set_retry_attempt(0)
     while True:
         stream: Any = None
         pre_run_items: list[Any] = []
@@ -785,6 +825,7 @@ async def _run_cycle(  # noqa: PLR0912, PLR0915
                     exc,
                 )
                 await asyncio.sleep(delay)
+                request_log.set_retry_attempt(model_retries)
                 if session is not None:
                     input_data = []
                 continue
@@ -792,7 +833,9 @@ async def _run_cycle(  # noqa: PLR0912, PLR0915
                 await _salvage_stream_to_session(session, pre_run_items, stream, agent_id)
             if isinstance(exc, ProviderRefusalError):
                 logger.warning("agent %s refused by the model provider: %s", agent_id, exc)
-                await coordinator.set_status(agent_id, "failed", error=str(exc))
+                await coordinator.set_status(
+                    agent_id, "failed", error=request_log.failure_text(exc)
+                )
                 await notify_parent_on_terminal(coordinator, agent_id, "failed")
                 return None
             if isinstance(exc, MaxTurnsExceeded):
@@ -806,7 +849,7 @@ async def _run_cycle(  # noqa: PLR0912, PLR0915
             # non-interactive agent's task: a child that dies still owes its parent a
             # report, and the parent would otherwise wait out its timeout on a message
             # the dead child can no longer send.
-            await coordinator.set_status(agent_id, status, error=str(exc) or type(exc).__name__)
+            await coordinator.set_status(agent_id, status, error=request_log.failure_text(exc))
             await notify_parent_on_terminal(coordinator, agent_id, status)
             if not interactive:
                 raise

strix/core/runner.py

@@ -59,10 +59,8 @@ if TYPE_CHECKING:
 
     from strix.runtime.status import StatusSink
     from strix.tools.mcp import (
-        ConnectedMcpServer,
         McpConnectionRequest,
         McpRegistry,
-        SupervisedMcpSession,
     )
 
 
@@ -71,8 +69,8 @@ logger = logging.getLogger(__name__)
 StreamEventSink = Callable[[str, Any], None]
 
 # Receives the run's MCP connection roster as a list of non-secret status dicts
-# ({"name", "provider", "tool_count", "dead"}), once when the connections are
-# established and again each time a connection transitions to dead. An interface
+# ({"name", "provider", "tool_count", "dead", "state"}), once when the connections
+# are registered and again on lifecycle transitions. An interface
 # can persist it, render it, or forward it on as connection status. Kept as a
 # snapshot of the whole roster (not a per-
 # connection delta) so every call carries a consistent, current picture.
@@ -80,30 +78,21 @@ McpStatusSink = Callable[[list[dict[str, Any]]], None]
 
 
 def _mcp_roster_payload(registry: McpRegistry) -> list[dict[str, Any]]:
-    """The run's MCP roster as non-secret status dicts (name/provider/tool_count/dead)."""
+    """The run's MCP roster as non-secret lifecycle status dicts."""
     return [
         {
             "name": status.name,
             "provider": status.provider,
             "tool_count": status.tool_count,
             "dead": status.dead,
+            "state": status.state,
         }
         for status in registry.statuses()
     ]
 
 
-def _mcp_startup_summary(connections: list[ConnectedMcpServer]) -> str:
-    """One user-facing line summarizing the MCP servers that connected."""
-    server_count = len(connections)
-    tool_count = sum(c.tool_count for c in connections)
-    servers_word = "server" if server_count == 1 else "servers"
-    tools_word = "tool" if tool_count == 1 else "tools"
-    names = ", ".join(c.name for c in connections)
-    return f"MCP: connected {server_count} {servers_word} ({tool_count} {tools_word}): {names}"
-
-
-def _record_mcp_connections(connections: list[ConnectedMcpServer]) -> None:
-    """Record which MCP servers this run connected, for the interfaces.
+def _record_mcp_connections(connection_names: list[str]) -> None:
+    """Record which MCP servers this run configured, for the interfaces.
 
     A server's tools are offered to the model under a name built from the
     connection name and the tool's own name, which cannot be split back apart, so
@@ -114,7 +103,7 @@ def _record_mcp_connections(connections: list[ConnectedMcpServer]) -> None:
     report_state = get_global_report_state()
     if report_state is None:
         return
-    report_state.record_mcp_connections([connection.name for connection in connections])
+    report_state.record_mcp_connections(connection_names)
 
 
 def _note_exit_reason(reason: str) -> None:
@@ -348,7 +337,7 @@ async def run_strix_scan(
     configure_spill_writer(_spill_to_workspace)
 
     sessions_to_close: list[SQLiteSession] = []
-    mcp_sessions: list[SupervisedMcpSession] = []
+    mcp_registry: McpRegistry | None = None
 
     try:
         targets = scan_config.get("targets") or []
@@ -400,7 +389,6 @@ async def run_strix_scan(
         from strix.tools.mcp import (
             McpConnectionRequest,
             McpRegistry,
-            attach_mcp_requests,
             load_user_mcp_configs,
         )
 
@@ -416,56 +404,37 @@ async def run_strix_scan(
             else:
                 mcp_requests = mcp_connection_requests
             if mcp_requests:
-                connections = await attach_mcp_requests(mcp_requests, mcp_registry)
-                mcp_sessions = [c.session for c in connections]
-                # Recorded even when nothing connected, so a resumed run does not
-                # keep attributing tool calls to servers it no longer has.
-                _record_mcp_connections(connections)
-                if connections:
-                    report(_mcp_startup_summary(connections))
-                    # Name the connected servers in the prompt so every agent
-                    # (root and children, both deriving from scope_context) sees
-                    # what is available at the start; they can still re-list or
-                    # inspect them at run time via list_mcps / describe_mcp. Set
-                    # only when a connection exists, so a run with no MCP leaves
-                    # the prompt context unchanged.
-                    scope_context["mcp_available"] = bool(mcp_registry)
-                    scope_context["mcp_connections"] = [
-                        {
-                            "name": summary.name,
-                            "purpose": summary.purpose,
-                            "tool_count": summary.tool_count,
-                        }
-                        for summary in mcp_registry.summaries()
-                    ]
+                for request in mcp_requests:
+                    mcp_registry.register(request)
+                _record_mcp_connections(mcp_registry.names())
+                report(
+                    f"MCP: configured {len(mcp_registry)} connection(s); "
+                    "warming them in the background"
+                )
+                scope_context["mcp_available"] = True
+                scope_context["mcp_connections"] = [
+                    {
+                        "name": summary.name,
+                        "purpose": summary.purpose,
+                        "tool_count": summary.tool_count,
+                    }
+                    for summary in mcp_registry.summaries()
+                ]
 
-                    # Feed a non-secret connection roster (name / provider /
-                    # tool_count / dead) to two consumers: once now (all
-                    # currently healthy) and again whenever a connection later
-                    # dies. It is always persisted to run.json so the viewer,
-                    # which re-reads the run's files from disk, can render the
-                    # MCP connections panel and health without an in-memory
-                    # sink. When an interface sink is attached (the TUI backend,
-                    # or pro forwarding into the app's event stream) it also
-                    # receives the same snapshot. In-use is derived separately by
-                    # each interface from the connection-tagged tool-call events,
-                    # so it is not carried here.
-                    def _emit_mcp_status() -> None:
-                        roster = _mcp_roster_payload(mcp_registry)
-                        _persist_mcp_status(roster)
-                        if mcp_status_sink is not None:
-                            try:
-                                mcp_status_sink(roster)
-                            except Exception:
-                                logger.exception("MCP status sink failed")
+                def _emit_mcp_status() -> None:
+                    roster = _mcp_roster_payload(mcp_registry)
+                    _persist_mcp_status(roster)
+                    if mcp_status_sink is not None:
+                        try:
+                            mcp_status_sink(roster)
+                        except Exception:
+                            logger.exception("MCP status sink failed")
 
-                    for connection_name in mcp_registry.names():
-                        entry = mcp_registry.get(connection_name)
-                        if entry is not None:
-                            entry.session.set_on_dead(_emit_mcp_status)
-                    _emit_mcp_status()
+                mcp_registry.set_status_sink(_emit_mcp_status)
+                _emit_mcp_status()
+                mcp_registry.start_warmup(max_concurrency=6)
         except Exception:
-            logger.exception("Failed to connect user MCP servers; continuing without them")
+            logger.exception("Failed to configure user MCP servers; continuing without them")
 
         root_context = _merge_root_prompt_context(scope_context, extra_system_prompt_context)
         root_instructions = _compose_root_instructions_override(
@@ -661,9 +630,9 @@ async def run_strix_scan(
         for s in sessions_to_close:
             with contextlib.suppress(Exception):
                 s.close()
-        for mcp_session in mcp_sessions:
+        if mcp_registry is not None:
             with contextlib.suppress(Exception):
-                await mcp_session.aclose()
+                await mcp_registry.close()
         with contextlib.suppress(Exception):
             await coordinator._maybe_snapshot()
         if cleanup_on_exit:

strix/skills/cloud/aws.md

@@ -94,6 +94,8 @@ curl https://BUCKET.s3.amazonaws.com/
 
 ### IAM Privilege Escalation
 
+**Resource control policies:** AWS Organizations RCPs impose an organization-level limit on supported resources, including access by external principals. Map resource-account RCPs as well as principal-account SCPs, identity/resource policies, session policies, and permission boundaries when assessing a cross-account or leaked-key path. RCPs do not grant access and do not apply uniformly to every service; an identity-policy allow alone does not describe the effective permission ([AWS RCP documentation](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_rcps.html)).
+
 Common escalation paths (verify with `aws iam simulate-principal-policy` when possible):
 
 | Permission | Escalation |

strix/skills/cloud/kubernetes.md

@@ -32,6 +32,10 @@ Kubernetes clusters expose a large attack surface through their API server, kube
 
 ## Key Vulnerabilities
 
+### Ingress-NGINX Admission
+
+Inventory validating-webhook reachability from the pod network and the controller's service-account permissions. IngressNightmare illustrates controller execution without a Kubernetes account ([advisory](https://kubernetes.io/blog/2025/03/24/ingress-nginx-cve-2025-1974/)). Identify the controller implementation/image, then verify affected builds, backports, and maintenance status against current project or vendor notices; distinguish community ingress-nginx from other NGINX controllers and the Ingress API ([project notice](https://kubernetes.io/blog/2026/01/29/ingress-nginx-statement/)).
+
 ### RBAC Misconfigurations
 
 - Wildcard verbs or resources in ClusterRole/Role bindings: `verbs: ["*"]`, `resources: ["*"]`

strix/skills/frameworks/django.md

@@ -57,6 +57,11 @@ Map endpoints, authentication classes, and permission classes per route.
 
 ## Key Vulnerabilities
 
+### Request and Spatial Input Handling
+
+- Under ASGI, compare underscore/hyphen forms of proxy-injected identity headers through `ASGIRequest` normalization into `request.META`. Resolve the installed branch, vendor backports, and support status from package metadata and current Django release/advisory information ([header-collision advisory](https://www.djangoproject.com/weblog/2026/apr/07/security-releases/)).
+- For GeoDjango, trace attacker-controlled spatial lookup strings/dictionaries into `GDALRaster`: driver behavior can turn them into server-side requests or file writes. Include custom filter APIs and admin changelist filtering; direct model-field assignment is a separate input path ([spatial lookup advisory](https://www.djangoproject.com/weblog/2026/aug/04/security-releases/)).
+
 ### Authentication & Authorization
 
 **Permission Class Gaps**
@@ -207,7 +212,7 @@ Static analysis is the fastest way to reach the sinks above in white-box scope.
 - **pip-audit** (PyPA) — dependency CVE scanner for known-vuln Django/DRF/simplejwt versions: `pipx install pip-audit && pip-audit -r requirements.txt`
 - **ast-grep** (preinstalled) — quick structural grep for risky calls without a full SAST run: `ast-grep run -p 'mark_safe($X)' -l python`
 
-For the `SECRET_KEY` → signed-cookie/reset-token forgery path noted under Session Issues, Django's own `django.core.signing` is the "tool": with a leaked key you can mint valid `signing.dumps()` values (session cookies, password-reset tokens, and `PickleSerializer`-backed session RCE).
+For the `SECRET_KEY` → signed-cookie forgery path noted under Session Issues, Django's own `django.core.signing` is the "tool": with a leaked key you can mint valid `signing.dumps()` values using the consumer's serializer and signing salt. Inspect `SESSION_SERIALIZER` and the installed implementation: the session-RCE path requires a reachable pickle-backed serializer; JSON sessions do not provide it. Password-reset tokens instead use `PasswordResetTokenGenerator`, with user state and timestamp in the digest, rather than the generic `signing.dumps()` format ([Django 5.0 removals](https://docs.djangoproject.com/en/5.0/releases/5.0/#features-removed-in-5-0), [token implementation](https://github.com/django/django/blob/stable/5.2.x/django/contrib/auth/tokens.py)).
 
 ## Summary
 

strix/skills/frameworks/fastapi.md

@@ -58,6 +58,12 @@ For each route, identify:
 
 ## Key Vulnerabilities
 
+### Starlette Request Handling
+
+Resolve Starlette's version independently of FastAPI and identify the ASGI server/front proxy. Check current upstream advisories and any vendor backports for the installed build before treating a parser issue as applicable. Compare middleware authorization against the actual routed path: malformed Host values can alter reconstructed `request.url` without changing routing ([URL parsing advisory](https://github.com/Kludex/starlette/security/advisories/GHSA-86qp-5c8j-p5mr)).
+
+For `request.form()`, test URL-encoded and multipart limits separately; a limit enforced on one parser may not constrain the other. Check whether crossing an upload's memory-to-disk spool threshold blocks the event loop ([form limits](https://github.com/Kludex/starlette/security/advisories/GHSA-82w8-qh3p-5jfq), [file spooling](https://github.com/Kludex/starlette/security/advisories/GHSA-2c2j-9gv5-cj73)).
+
 ### Authentication & Authorization
 
 **Dependency Injection Gaps**

strix/skills/frameworks/nestjs.md

@@ -78,6 +78,13 @@ For each controller and method, identify:
 
 ## Key Vulnerabilities
 
+### Adapter and Schema Version Boundaries
+
+- **Express adapter:** resolve the installed Nest/Express versions and effective query-parser setting from configuration or a harmless nested-query probe. Apply `qs`/nested-operator attacks only when the parser constructs nested objects. Check the matching router documentation and test both root and child paths against authentication middleware ([migration reference](https://nestjs.io/tutorials/what-s-new-in-express-5-eeb51579)).
+- **Fastify adapter:** inspect the installed version's schema requirements and any custom validator configuration. Verify whether the route schema is actually enforced before relying on a DTO or shorthand-schema declaration ([migration reference](https://fastify.dev/docs/v5.0.x/Guides/Migration-Guide-V5/)).
+- **Standard Schema, where supported:** `@Body({ schema })`, `@Query({ schema })`, `@Param(..., { schema })`, and `@RawBody({ schema })` attach metadata; enforcement requires `StandardSchemaValidationPipe`. Probe schema-decorated routes for accepted invalid values when the pipe is absent or transport-local. Outgoing schema enforcement uses `StandardSchemaSerializerInterceptor`; check actual output rather than relying only on class-transformer decorators.
+- **GraphQL transport:** inspect installed packages, enabled IDE, and negotiated WebSocket subprotocol. Verify supported/deprecated transports against the matching Nest documentation, then recheck connection and per-operation authentication on the deployed transport ([migration guide](https://docs.nestjs.com/migration-guide)).
+
 ### Guard Bypass
 
 **Decorator Stack Gaps**

strix/skills/frameworks/nextjs.md

@@ -12,7 +12,7 @@ Security testing for Next.js applications. Focus on authorization drift across r
 **Routers**
 - App Router (`app/`) and Pages Router (`pages/`) often coexist
 - Route Handlers (`app/api/**`) and API routes (`pages/api/**`)
-- Middleware: `middleware.ts` at project root
+- Middleware/proxy: inspect `middleware.ts`, `proxy.ts`, installed Next.js metadata, and runtime configuration. Check the matching framework docs for supported filenames, Node/Edge behavior, and feature status before selecting runtime-specific probes ([migration guide](https://nextjs.org/docs/app/guides/upgrading/version-16)).
 
 **Runtimes**
 - Node.js (full API access)
@@ -43,6 +43,8 @@ Security testing for Next.js applications. Focus on authorization drift across r
 
 ## Reconnaissance
 
+At each assessment, establish the deployed build from package metadata, lockfiles, or runtime evidence. Verify release/support status and applicable fixes through current official docs, advisories, or upstream source; linked advisories are starting points, not a complete or permanently current list. Recheck when the target build or proposed remediation changes, and mark status unverified if evidence is unavailable.
+
 **Route Discovery**
 
 ```javascript
@@ -83,10 +85,15 @@ Inspect Network tab for POST requests with `Next-Action` header. Extract action
 
 ## Key Vulnerabilities
 
+### RSC and Image Processing
+
+- **React2Shell (CVE-2025-55182):** App Router applications can expose the vulnerable RSC decoder without explicit Server Actions. Identify the bundled `react-server-dom-*` implementation and trace requests into decoding; client-only React and Pages-only apps have different exposure. Check the framework's patched branch, including source-disclosure and DoS fixes ([RCE advisory](https://react.dev/blog/2025/12/03/critical-security-vulnerability-in-react-server-components), [RSC advisories](https://react.dev/blog/2025/12/11/denial-of-service-and-source-code-exposure-in-react-server-components)).
+- Treat `/_next/image` optimization and Node `next/og` `ImageResponse` as separate input paths. Trace attacker-controlled image bytes into native decoders, and SVG content/attributes/styles into image construction. URL allowlisting does not make image contents trusted; match the decoder, runtime, and Next.js version to the relevant advisory ([optimizer](https://nextjs.org/blog/august-2026-security-release), [ImageResponse](https://github.com/vercel/next.js/security/advisories/GHSA-vcvr-r3jv-pc5j)).
+
 ### Middleware Bypass
 
 **Known Techniques**
-- `x-middleware-subrequest` header crafting (CVE-class bypass)
+- `x-middleware-subrequest` header crafting (CVE-2025-29927): middleware-only authorization can be skipped on affected deployments. Resolve the installed branch and hosting protections from the advisory and provider configuration, then check whether external headers reach the origin and the destination enforces authorization independently ([advisory](https://github.com/vercel/next.js/security/advisories/GHSA-f82v-jwr5-mffw)).
 - `x-nextjs-data` probing
 - Look for 307 + `x-middleware-rewrite`/`x-nextjs-redirect` headers
 
@@ -118,7 +125,7 @@ Middleware checks first value, handler uses last or array.
 **Cache Boundary Failures**
 - User-bound data cached without identity keys (ETag/Set-Cookie unaware)
 - Personalized content served from shared cache/CDN
-- Missing `no-store` on sensitive fetches
+- Missing `no-store` on sensitive fetches matters only when they enter a shared cache. Determine `fetch` and GET Route Handler defaults for the deployed version from docs/configuration and observed responses. Where Cache Components are enabled, inspect `use cache` arguments/closed-over values, `cacheTag`, `cacheLife`, and invalidation for user/tenant separation ([caching documentation](https://nextjs.org/docs/app/getting-started/cache-components)).
 
 **Flight Data Leakage**
 

strix/skills/protocols/graphql.md

@@ -134,6 +134,10 @@ Parser precedence varies; may bypass validation. Also test default argument valu
 
 Send unexpected keys in input objects; backends may pass them to resolvers or downstream logic.
 
+### OneOf Inputs
+
+Discover `@oneOf` input types through the schema or `__Type.isOneOf`. They require exactly one non-null field, with every other field omitted. Test both inline literals and variables with zero fields, two selectors, and an extra null-valued selector; all must fail coercion. Then test authorization independently for each valid selector (ID, username, organization/email), since schema exclusivity does not ensure identical tenant checks in each resolver branch. Confirm the deployed implementation supports OneOf before treating acceptance as a specification violation ([GraphQL September 2025](https://spec.graphql.org/September2025/#sec-OneOf-Input-Objects)).
+
 ### Cursor Manipulation
 
 Decode cursors (usually base64) to:

strix/skills/protocols/oauth.md

@@ -77,7 +77,7 @@ com.app://callback  (mobile custom scheme)
 
 ### State and Nonce
 
-- Missing, predictable, or reusable `state` → CSRF on OAuth login (session fixation, account linking)
+- Missing, predictable, or reusable `state` → test CSRF on OAuth login (session fixation, account linking); RFC 9700 also permits correctly bound PKCE, or OIDC `nonce`, to provide CSRF protection, so establish whether that protection survives a cross-session callback
 - Missing `nonce` in OIDC → ID token injection/replay
 - `state` not bound to client session or PKCE verifier
 
@@ -102,7 +102,7 @@ com.app://callback  (mobile custom scheme)
 ### Scope and Token Issues
 
 - Scope escalation: request `admin`/`offline_access`/`openid profile email` beyond app need; server grants all requested scopes
-- Refresh token not rotated or reuse not detected → persistent access
+- Public-client refresh tokens neither sender-constrained nor rotated with reuse detection → persistent access; a non-rotating token bound to the client's key is permitted by RFC 9700, so test replay without that key
 - Access token accepted across services (missing audience/resource binding)
 - Token introspection returns `active:true` without proper auth on introspection endpoint
 
@@ -113,6 +113,10 @@ com.app://callback  (mobile custom scheme)
 - Userinfo endpoint returns PII without matching access token scope
 - `sub` collision across issuers if `iss` not validated
 
+### OAuth Security BCP (RFC 9700)
+
+Authorization servers must support PKCE, public clients must use it, and confidential clients are also recommended to use it. Test challenge stripping and verifier injection across both client types. Resource-owner-password grants must not be used; implicit access-token responses are discouraged because tokens can leak or be replayed. For mix-up defenses, bind the selected issuer and endpoints to the authorization transaction; validate an authorization-response `iss` when that defense is used, rather than merely checking the issuer of a later ID token ([RFC 9700](https://www.rfc-editor.org/rfc/rfc9700.html)).
+
 ## Advanced Techniques
 
 **Referer Leakage**

strix/skills/technologies/active_directory.md

@@ -100,6 +100,13 @@ certipy find -u <USER>@<DOMAIN> -p <PASS> -dc-ip <DC_IP> -vulnerable -stdout
 - **ESC8** — NTLM relay to the CA web-enrollment endpoint (coerce a DC, relay to `/certsrv`) → DC certificate → DCSync.
 - **ESC others** — ESC2/3 (any-purpose/enrollment-agent), ESC4 (writable template DACL → make it ESC1), ESC6 (`EDITF_ATTRIBUTESUBJECTALTNAME2` on the CA), ESC7 (CA officer rights), ESC9/10 (weak cert mapping), ESC11 (RPC relay), ESC13 (issuance-policy→group), ESC15 (app-policy on v1 templates). `certipy find -vulnerable` flags each.
 
+**Strong certificate mapping:** establish the DC patch level, mapping policy, and vendor backports; consult Microsoft's current enforcement guidance before assuming Compatibility mode is available. Inspect template SID extensions, explicit mappings, and the principal selected at authentication. A requested privileged UPN alone does not establish a working ESC chain ([KB5014754](https://support.microsoft.com/en-us/servicing/os/windows-server/2022/05/kb5014754-certificate-based-authentication-changes-on-windows-domain-controllers)).
+
+### Windows Server 2025 dMSA / BadSuccessor
+
+- **CVE-2025-53779:** on unpatched Server 2025 DCs, control sufficient to create/modify a delegated Managed Service Account can establish a one-way migration link to another principal and obtain its authority/keys through the KDC. Enumerate dMSA creation rights, object ACLs, and migration attributes rather than limiting discovery to conventional service accounts and delegation flags.
+- **Patched behavior:** the KDC requires mutual dMSA↔target linkage. Writing the dMSA-side attribute still succeeds, so LDAP write success is not proof of exploitation. Determine whether the tester also controls the target object's reciprocal link and whether the KDC actually issues the relevant ticket. Post-patch abuse is a different prerequisite chain from the original low-privilege OU-control escalation ([researchers' patch analysis](https://www.akamai.com/blog/security-research/badsuccessor-is-dead-analyzing-badsuccessor-patch)).
+
 ### NTLM Coercion & Relay
 
 Force a privileged machine to authenticate to you, then relay that NTLM auth to a service that doesn't enforce signing/EPA (LDAP, AD CS, SMB).

strix/skills/technologies/auth0.md

@@ -86,12 +86,14 @@ Authorization: Bearer <token_with_audience_A>
 
 ### Rules and Actions Abuse
 
+Inventory which Rules, Hooks, and Actions actually execute in the tenant. Check the current Auth0 lifecycle notice and tenant capabilities for retirement or read-only restrictions. During migration, compare claim assignment, MFA, denial decisions, and account-linking checks across every connection; distinguish secret/configuration access from source-code modification ([lifecycle notice](https://auth0.com/docs/troubleshoot/product-lifecycle/deprecations-and-migrations#rules-and-hooks-deprecations)).
+
 **Post-Login Rule/Action Injection**
 - Rules that add claims based on unvalidated user metadata:
   ```javascript
   user.app_metadata.role = 'admin'  // if user can set app_metadata via signup/API
   ```
-- `context.authorization` manipulation in Actions
+- Rules use `context`; Actions receive `event` and enforce token/MFA/denial changes through `api` methods. Test migrated checks that only mutate event data: those mutations do not propagate to other Actions or substitute for the corresponding enforcement API ([migration behavior](https://auth0.com/docs/customize/actions/migrate/migrate-from-rules-to-actions)).
 - Secrets in Rule code exposed to tenant admins or via Management API leak
 
 **Signup / Registration Actions**

strix/skills/technologies/grafana_prometheus.md

@@ -79,6 +79,13 @@ Unauthenticated view (and, with `public_mode`, delete) of the lowest-key snapsho
 ### Prometheus / Alertmanager — exposure is the vuln (no auth by default)
 Prometheus and Alertmanager ship with **no authentication**; the docs explicitly say do not expose them. There is rarely a CVE — reachability itself is the finding, and the payoff is recon + credential leakage + pivoting (below).
 
+## Plugin and MCP Boundaries
+
+Resolve installed Grafana, plugin, and MCP server builds separately; check current upstream advisories and vendor backports before applying a listed attack path or recommending a release.
+
+- Plugin archives are extracted before signature verification. Test chained symlinks and containment before trusting a signature failure to prevent filesystem writes; archive installation is the required trigger ([extraction advisory](https://grafana.com/security/security-advisories/cve-2026-15815/)).
+- Inventory mcp-grafana separately from Grafana. Trace `grafana_api_request` and `X-Grafana-URL` into destination selection; preventing token forwarding alone does not prevent SSRF ([MCP advisory](https://grafana.com/security/security-advisories/cve-2026-19516/)).
+
 ## Pivoting: Observability → Deeper Compromise
 
 This is the core value. Chain each exposure into something that matters. Always articulate the pivot in the finding, not just the exposed endpoint.

strix/skills/technologies/llm_applications.md

@@ -78,11 +78,11 @@ Record both forward and reverse reachability: attacker-controlled input to privi
 
 ## Optional Tool Routing
 
-Use tools only when they match the deployed surface. Treat generated cases and scanner labels as leads until the application-side boundary is validated.
+Use tools only when they match the deployed surface. Resolve compatible versions, runtime requirements, maintenance status, and advisories from registry metadata and current upstream documentation, then pin the exact reviewed versions for the run. Treat generated cases and scanner labels as leads until the application-side boundary is validated.
 
-- **[Promptfoo](https://github.com/promptfoo/promptfoo)** — use for repeatable model/application trials, custom adversarial cases, graders, provider comparisons, and success-rate regression. Install the reviewed version locally with `npm install --save-dev --save-exact promptfoo@0.122.0`, then invoke `./node_modules/.bin/promptfoo redteam run`. Define explicit plugins, assertions, `numTests`, `maxConcurrency`, and `delay`; provider calls may transmit test data and incur cost. Its `owasp:llm` preset still uses the 2025 category mapping in version 0.122.0, so build or select tests from the 2026 matrix above and do not present the preset report as complete 2026 coverage.
-- **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)** — use for LLM01/LLM03 surface mapping when MCP servers are present. Install the reviewed version with `npm install --save-dev --save-exact @modelcontextprotocol/inspector@2.2.0`, then use `./node_modules/.bin/mcp-inspector --cli --config <reviewed-config> --server <name> --method tools/list` and the equivalent `resources/list` / `prompts/list` operations. Starting a stdio server executes that configured process, initialization/list handlers may have side effects, and `tools/call` can perform the real action; inspect the target and credentials before invoking it.
-- **[ModelScan](https://github.com/protectai/modelscan)** — use for LLM04 static triage of supported H5, Pickle, and SavedModel artifacts before loading them, for example `uvx modelscan==0.8.8 -p <artifact>`. Run it as an untrusted-file parser in an isolated analysis environment. A clean result covers only the scanner's supported formats and signatures; it does not establish artifact provenance, integrity, or absence of behavioral backdoors.
+- **[Promptfoo](https://github.com/promptfoo/promptfoo)** — use for repeatable model/application trials, custom adversarial cases, graders, provider comparisons, and success-rate regression. Install the reviewed version locally with `npm install --save-dev --save-exact promptfoo@<reviewed-version>`, then invoke `./node_modules/.bin/promptfoo redteam run`. Define explicit plugins, assertions, `numTests`, `maxConcurrency`, and `delay`; provider calls may transmit test data and incur cost. Inspect the installed `owasp:llm` preset's category mapping and actual tests before claiming coverage; add cases for gaps against the assessment's chosen taxonomy.
+- **[MCP Inspector](https://github.com/modelcontextprotocol/inspector)** — use for LLM01/LLM03 surface mapping when MCP servers are present. Install the reviewed version with `npm install --save-dev --save-exact @modelcontextprotocol/inspector@<reviewed-version>`, then use `./node_modules/.bin/mcp-inspector --cli --config <reviewed-config> --server <name> --method tools/list` and the equivalent `resources/list` / `prompts/list` operations. Starting a stdio server executes that configured process, initialization/list handlers may have side effects, and `tools/call` can perform the real action; inspect the target and credentials before invoking it.
+- **[ModelScan](https://github.com/protectai/modelscan)** — use for LLM04 static triage of supported H5, Pickle, and SavedModel artifacts before loading them, for example `uvx modelscan==<reviewed-version> -p <artifact>`. Run it as an untrusted-file parser in an isolated analysis environment. A clean result covers only the scanner's supported formats and signatures; it does not establish artifact provenance, integrity, or absence of behavioral backdoors.
 
 ## LLM01:2026 Prompt Injection
 

strix/skills/technologies/supabase.md

@@ -35,7 +35,7 @@ Security testing for Supabase applications. Focus on mis-scoped Row Level Securi
 - Functions: `https://<ref>.functions.supabase.co/`
 
 **Headers**
-- `apikey: <anon-or-service>` — identifies project
+- `apikey: <publishable-or-secret-key>` — identifies the application component; legacy `anon` / `service_role` JWT keys can still coexist
 - `Authorization: Bearer <JWT>` — binds user context
 
 **Roles**
@@ -45,6 +45,13 @@ Security testing for Supabase applications. Focus on mis-scoped Row Level Securi
 **Key Principle**
 `auth.uid()` returns current user UUID from JWT. Policies must never trust client-supplied IDs over server context.
 
+### API Keys and Signing Keys
+
+- Opaque keys start with `sb_publishable_` or `sb_secret_`; JWT decoding will not classify them. Search bundles, server configuration, and responses for both formats. Publishable keys are intended for public clients; secret keys use `service_role` and bypass RLS. A browser 401 for a leaked secret key is not revocation: the browser restriction uses `User-Agent` and does not stop server-side use.
+- Creating new keys does not disable legacy keys. After migration, test whether the old `anon` / `service_role` credential remains accepted; dashboard revocation is a separate action. Verify supported key formats and migration/deprecation status from project settings and current Supabase documentation ([API keys](https://supabase.com/docs/guides/getting-started/api-keys)).
+- Edge Functions use user JWTs in `Authorization` and API keys in `apikey`. Verify the deployed platform's `verify_jwt` behavior with current docs and controlled requests, including API keys on either header; passing a platform check with a publishable key does not establish a signed-in user. Test whether the handler verifies user identity before using a privileged client. Conversely, `verify_jwt=false` with explicit secret-key or webhook verification is not necessarily public. Trace the configured `@supabase/server` auth mode or custom verification ([function authorization](https://supabase.com/docs/guides/functions/auth-headers)).
+- Asymmetric signing keys are discoverable at `/auth/v1/.well-known/jwks.json`. Test custom API/Edge Function validators for issuer/algorithm binding and stale cached keys after rotation/revocation. Measure cache lifetimes from response headers, SDK configuration, and controlled rotation tests; check service-specific revocation behavior in current documentation rather than assuming platform and custom validators share a cache ([signing keys](https://supabase.com/docs/guides/auth/signing-keys)).
+
 ## High-Value Targets
 
 - Tables with sensitive data (users, orders, payments, PII)

strix/skills/vulnerabilities/agentic_system_security.md

@@ -106,10 +106,16 @@ Classify each discovered integration by data read, data write, external communic
 - For each tool, validate the same authorization and argument checks through every supported transport.
 - Treat server-launched subprocess configuration, environment variables, and working directories as sensitive executable configuration.
 - For HTTP/SSE transports, validate OAuth issuer, signature, expiry, audience/resource, tenant, and scope claims at the server boundary. Reject tokens minted for the wrong audience, and do not treat a session ID as identity.
-- For downstream APIs, do not pass through the same bearer token unless the target explicitly authorizes that audience and principal. Separate upstream MCP authentication from downstream target authorization.
+- MCP forbids token passthrough: reject access tokens not issued for the MCP server, and use a separate downstream authorization flow instead of forwarding a client's token to another API ([MCP authorization](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)).
 - For browser or loopback OAuth, review redirect URI, state/PKCE handling, localhost binding, and consent proxying. Treat metadata fetches and tool discovery on remote servers as SSRF-relevant surfaces.
 - For stdio servers, the launch command and environment are already code execution. Discovery must not execute an unreviewed server binary or mutable package tag.
 
+#### MCP Protocol Boundaries
+
+- Identify the protocol revision and client/server SDK builds from configuration and wire traffic, then consult the matching specification and current SDK advisories. Determine whether the transport uses initialization/session IDs or independent requests with client metadata and discovery. Test authorization on every request; client-supplied identity/capabilities in `_meta` are not authenticated identity.
+- Where multi-round tool requests use `input_required` and `inputResponses`, trace the retry/resume binding. Test whether a response from another user, tool invocation, or approval round can be substituted, and whether a retry repeats a consequential action ([MCP protocol specification](https://blog.modelcontextprotocol.io/posts/2026-07-28/)).
+- For OAuth callbacks, bind the expected issuer from validated discovery to the PKCE transaction. A present `iss` must match exactly, even if metadata did not advertise support; an absent `iss` must be rejected when `authorization_response_iss_parameter_supported` is true. Test issuer changes between discovery, registration, and callback, including error callbacks. Bind client credentials to their authorization-server issuer. Require the MCP server's `resource` in authorization and token requests and validate the token's audience at the server ([authorization requirements](https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization)).
+
 ### Executable Component Supply Chain
 
 Every skill, plugin, MCP server, model adapter, package, and update channel is an executable or behavior-shaping dependency. Record:
@@ -158,7 +164,7 @@ npx @modelcontextprotocol/inspector@<reviewed-version> --cli \
   --method tools/list --format json
 ```
 
-- Current upstream requirements should be checked before pinning; as of August 12, 2026, MCP Inspector 2.1.0 requires Node.js `>=22.19.0`.
+- Before choosing MCP Inspector, inspect package-registry metadata, engine requirements, release notes, and advisories. Select a compatible reviewed version and pin that exact version for the run; do not infer safety from a release tag.
 - Prefer CLI/TUI and loopback binding over exposing the web UI.
 - Preserve the generated API token; never disable authentication or bind the process-spawning backend to an external interface.
 - Do not publish ports 6274/6277 or pass through the Docker socket/host devices.
@@ -173,7 +179,7 @@ npx @modelcontextprotocol/inspector@<reviewed-version> --cli \
 npx promptfoo@<reviewed-version> eval
 ```
 
-- Current upstream engine constraints should be checked before pinning; as of August 12, 2026, Promptfoo documents Node.js `^20.20.0` or `>=22.22.0`.
+- Resolve Promptfoo's runtime requirements, supported features, and security status from registry metadata and current upstream docs before choosing and pinning a version.
 - Use synthetic prompts/data and a dedicated test provider/project.
 - Provider calls transmit data externally and can incur cost even when evaluation orchestration is local. Set request/concurrency and spending ceilings.
 - Pin model, provider, prompt, tool schema, retrieval corpus revision, and evaluator versions.

strix/skills/vulnerabilities/browser_security.md

@@ -104,6 +104,12 @@ Prove the strongest reliable capability first. If escalation requires a user ges
 - Treat scriptless disclosure of a nonce or trusted URL as a primitive; prove a second controllable sink before claiming bypass.
 - For response splitting, consider whether a same-origin endpoint can be turned into a script resource with a controlled body length or framing.
 
+### Local Network and Loopback Access
+
+Identify the browser build, enabled flags, permission state, and enterprise policy; consult its current Local Network Access documentation and verify actual behavior with controlled requests. Test DNS rebinding and browser-to-local-service chains in both permission-denied and permission-granted states. A successful server-side request does not establish browser reachability ([Chrome LNA](https://developer.chrome.com/blog/local-network-access)).
+
+Discover which permission names and aliases the target supports, including `local-network`, `loopback-network`, and `local-network-access`. Record which destination class was permitted before claiming access to both LAN and localhost services ([permission reference](https://developer.chrome.com/release-notes/145#local_network_access_split_permissions)).
+
 ### JavaScript Gadget Discovery
 
 - When direct calls are blocked, inspect implicit coercions (`toString`, `valueOf`, iterators, getters, proxies) and callbacks invoked by accessible library functions.

strix/skills/vulnerabilities/http_request_smuggling.md

@@ -97,6 +97,12 @@ transfer-encoding: chunked
 SMUGGLED
 ```
 
+### CL.0, 0.CL, and Double Desync
+
+In CL.0, the front end honors `Content-Length` while the back end ignores the body; in 0.CL the front end ignores it while the back end expects it. The latter commonly deadlocks until an early-response gadget responds without consuming the body and keeps the connection open. Test redirects and early errors for that specific connection behavior. A subsequent controlled request can expose the boundary shift; two successive desyncs can convert 0.CL into CL.0. A lone timeout or 400 does not establish that chain.
+
+Include `Expect: 100-continue` handling and interim/final response sequencing in differential tests. Calculate offsets from what the back end receives, including proxy-added headers. Use controlled follow-up requests to establish which bytes are consumed and which response belongs to each request ([HTTP/1.1 must die](https://portswigger.net/research/http1-must-die), [0.CL walkthrough](https://portswigger.net/blog/http-1-1-must-die-conquering-the-0-cl-challenge)).
+
 ## Key Vulnerabilities
 
 ### Front-End Security Control Bypass

strix/skills/vulnerabilities/insecure_deserialization.md

@@ -79,6 +79,8 @@ JNDI injection is not itself a serialization format. It becomes part of this wor
 
 ### Python Pickle
 
+**Model checkpoints:** `torch.load(..., weights_only=True)` does not rule out parser/storage memory corruption. Resolve the installed loader build and check current upstream advisories/backports before trusting that flag. Trace untrusted checkpoints through the exact loader and inspect safe-global allowlists ([example advisory](https://github.com/pytorch/pytorch/security/advisories/GHSA-63cw-57p8-fm3p)).
+
 Pickle executes arbitrary code during unpickling by design:
 ```python
 import pickle, os, base64
@@ -101,13 +103,15 @@ When `yaml.load` used instead of `yaml.safe_load`.
 - POP chains through framework classes (Laravel, Symfony, WordPress plugins)
 
 **Phar Deserialization**
-- Upload or reference `phar://` wrapper triggering metadata deserialization on file operations
+- Trace `phar://` file operations and explicit `Phar::getMetadata()` / `PharFileInfo::getMetadata()` calls. Verify the installed PHP version's metadata-deserialization behavior and `allowed_classes` handling from source/docs; archive opening alone does not establish a deserialization sink ([migration reference](https://www.php.net/manual/en/migration80.incompatible.php#migration80.incompatible.phar)).
 
 ### .NET Deserialization
 
 **BinaryFormatter / LosFormatter**
 - Never safe on untrusted input; full RCE with known gadget chains (ysoserial.net)
 
+Inspect the target framework and resolved serialization packages to establish whether `BinaryFormatter` executes, throws, or is restored through a compatibility package. Check the matching runtime documentation before choosing gadget chains; `LosFormatter` and other serializers are separate surfaces ([Microsoft guide](https://learn.microsoft.com/en-us/dotnet/standard/serialization/binaryformatter-migration-guide/)).
+
 **Json.NET**
 ```json
 {"$type":"System.Windows.Data.ObjectDataProvider, PresentationFramework", ...}
@@ -193,7 +197,7 @@ Payload generation is the practitioner's core tool here. The sandbox has `git`/`
 | **ysoserial** (frohoff) | Java native | Gadget-chain payloads: `CommonsCollections1-7`, `Groovy1`, `Spring1/2`, and `URLDNS` for a safe no-exec DNS oracle. Needs a JRE. |
 | **phpggc** (ambionics) | PHP `unserialize` / Phar | Framework POP chains (Laravel, Symfony, WordPress, Drupal, Monolog). Needs `php-cli`. |
 | **ysoserial.net** | .NET `BinaryFormatter` / Json.NET | Windows/.NET gadget payloads. Needs .NET/mono — usually out of scope in a Linux sandbox. |
-| **marshalsec** | Java Hessian/Burlap, Kryo, JSON, and JNDI reference tooling | Use only from a reviewed, pinned upstream commit when a non-native Java marshaller requires it. It has no stable release and intentionally bundles historical gadget dependencies; do not treat it as a globally installed default tool. |
+| **marshalsec** | Java Hessian/Burlap, Kryo, JSON, and JNDI reference tooling | Use only from a reviewed, pinned upstream commit when a non-native Java marshaller requires it. Check upstream release status and bundled gadget dependencies before selecting a commit; do not treat it as a globally installed default tool. |
 
 ```
 # Java: prove the sink with a no-exec DNS oracle BEFORE any RCE chain

strix/skills/vulnerabilities/nosql_injection.md

@@ -91,7 +91,7 @@ Binary search the character space to minimize requests. Works on any string fiel
 
 ### `$where` JavaScript Injection
 
-If `$where` operator is enabled (disabled by default in MongoDB 7.0+; MongoDB 4.4–6.x deprecated it but left `javascriptEnabled` defaulting to `true`), inject arbitrary server-side JavaScript:
+If `$where` is enabled, inject server-side JavaScript. Inspect `security.javascriptEnabled` / `--noscripting`, managed-service restrictions, and the installed engine version. Verify operator availability, defaults, and supported functions against that build's documentation or controlled probes; deprecation alone does not mean execution is disabled ([MongoDB documentation](https://www.mongodb.com/docs/manual/reference/operator/query/where/)):
 ```json
 {"$where": "function(){return this.role == 'admin'}"}                          // direct filter — returns matching documents
 {"$where": "function(){return this.username == 'admin' && sleep(2000)}"}       // timing oracle only — sleep() returns undefined (falsy), so no documents are returned; observe latency

strix/skills/vulnerabilities/path_traversal_lfi_rfi.md

@@ -148,6 +148,8 @@ Improper file path handling and dynamic inclusion enable sensitive file disclosu
 - Verify symlink handling and path canonicalization prior to write
 - Impact: overwrite config/templates or drop webshells into served directories
 
+**Python extraction filters:** Determine the effective `filter` and `TarFile.extraction_filter` from the installed Python runtime, caller configuration, and matching documentation; verify patch/backport status against current advisories ([documentation](https://docs.python.org/3/library/tarfile.html#extraction-filters)). Filters do not eliminate link-handling bugs: test archive link ordering and post-extraction reads for outside-file disclosure or permission/timestamp changes, separately from content overwrite ([security advisory](https://mail.python.org/archives/list/[email protected]/thread/EFJWGAZJA56AKSBR2WHMHQZO7RRLZPRH/)).
+
 ### File Write to Execution
 
 Characterize the write primitive before choosing a payload:

strix/skills/vulnerabilities/prototype_pollution.md

@@ -51,7 +51,7 @@ Prototype pollution corrupts shared object prototypes (`Object.prototype`, `Arra
 **Common Sinks**
 - `lodash.merge`, `lodash.defaultsDeep`, `deep-extend`, `merge-options`
 - Express/query parsers accepting nested objects
-- YAML `load()` (not `safeLoad`) with prototype keys
+- YAML merge-key handling with prototype keys: identify the js-yaml version/schema and check applicable upstream advisories. Test whether `<<` merges alter the parsed result's prototype, then trace inherited values into a sensitive consumer; global `Object.prototype` modification is not required. Verify the installed API rather than assuming `load` versus `safeLoad` determines safety ([merge advisory](https://github.com/nodeca/js-yaml/security/advisories/GHSA-mh29-5h37-fv8m)).
 - JSON.parse → merge into existing object without null prototype
 
 **RCE Gadget Chains (Node.js)**

strix/skills/vulnerabilities/ssti.md

@@ -76,6 +76,8 @@ When output isn't reflected:
 
 ### Jinja2 / Mako (Python)
 
+**Jinja sandbox:** resolve the installed Jinja build and check current sandbox advisories before selecting indirect `str.format` or `|attr` gadgets. Establish template-source control and inspect custom filters; user data passed only as a variable is a different surface ([release notes](https://jinja.palletsprojects.com/en/stable/changes/)).
+
 The classic Python class walk — every object exposes its method-resolution-order, which leads to `object`, which exposes every subclass loaded in the interpreter, which includes things like `subprocess.Popen`:
 
 ```jinja
@@ -137,7 +139,7 @@ Twig sandbox bypasses are version-specific. The canonical historical gadget (Twi
 {{_self.env.registerUndefinedFilterCallback("system")}}{{_self.env.getFilter("id")}}
 ```
 
-This was patched — in Twig 2.x / 3.x `_self` returns the template name as a string and no longer exposes `.env`. Modern bypasses depend on which extensions are loaded and the active sandbox policy; consult Twig's published security advisories for the current state and probe with the version-specific gadgets (filter/function abuse, reflection on `_context` in some configs).
+In Twig 2.x / 3.x, `_self` returns the template name as a string and does not expose `.env`. Bypasses depend on which extensions are loaded and the active sandbox policy; consult Twig's published security advisories and probe with the version-specific gadgets (filter/function abuse, reflection on `_context` in some configs).
 
 Smarty `{php}...{/php}` was the historical RCE primitive; deprecated in Smarty 3 and removed in 4. On modern Smarty, the surface is static-method invocation and template-object reflection — `{$smarty.template_object->smarty->...}` walks back to the Smarty engine, and direct static calls on whitelisted classes (e.g. `{Smarty_Internal_Write_File::writeFile(...)}` on misconfigured installs) reach the filesystem. Probe both before assuming Smarty is hardened.
 

strix/skills/vulnerabilities/weak_password_detection.md

@@ -49,13 +49,15 @@ Weak or default credentials remain one of the most prevalent and high-impact vul
 
 ### Weak Password Policies
 
-- No minimum length or complexity requirements
+- Insufficient minimum length for the authentication mode; NIST SP 800-63B-4 requires 15 characters for single-factor passwords and permits a minimum of eight when the password is only used as part of MFA
 - Allowing common passwords: `password`, `123456`, `qwerty`, `admin`, `letmein`
 - Not checking against breached password databases (Have I Been Pwned)
 - Case-insensitive password storage
-- No password history enforcement
+- Forced periodic changes without compromise evidence, which encourage predictable password changes
 - Excessively short maximum length (indicates plaintext or weak hashing)
 
+NIST SP 800-63B-4 recommends allowing a maximum of at least 64 characters and requires screening against common/compromised passwords and checking the entire password without truncation. Missing character-class rules is not a weakness: the standard prohibits mandatory composition rules and periodic resets without evidence of compromise. Apply these requirements when that standard is the target's policy baseline ([NIST SP 800-63B-4](https://pages.nist.gov/800-63-4/sp800-63b.html#passwordver)).
+
 ### Default and Hardcoded Credentials
 
 - Vendor defaults: `admin/admin`, `admin/password`, `root/root`, `guest/guest`
@@ -191,7 +193,7 @@ No password wordlists ship in the sandbox by default — download what you need
 5. Test for password spraying (one password, many users) before targeted brute-force
 6. Check for concurrent session limits; successful logins may kick out legitimate users
 7. GraphQL batching can test multiple credentials in a single request, bypassing per-request limits
-8. Document the password policy and recommend minimum standards (length, complexity, breach checking)
+8. Document the password policy and recommend minimum standards (length appropriate to single-factor/MFA use, breach checking, and resistance to online guessing)
 9. For web logins prefer `ffuf`; for other services use `nmap` NSE `*-brute` scripts or custom scripts with equivalent logic
 10. Combine with MFA testing: weak passwords plus missing MFA is a critical finding
 

strix/skills/vulnerabilities/xss.md

@@ -53,6 +53,10 @@ Cross-site scripting persists because context, parser, and framework edges are c
 
 ## Key Vulnerabilities
 
+### DOMPurify Live-Node Sanitization
+
+Distinguish HTML-string input from live DOM objects sanitized with `IN_PLACE`. Resolve the deployed DOMPurify build and check relevant upstream advisories; a controlled observable `nodeName` is one live-node bypass mechanism. Trace same-origin foreign nodes or `adoptNode()` into this mode before selecting the bypass ([example advisory](https://github.com/cure53/DOMPurify/security/advisories/GHSA-x4vx-rjvf-j5p4)).
+
 ### DOM XSS
 
 **Sources**

strix/tools/mcp/__init__.py

@@ -2,7 +2,13 @@
 
 from __future__ import annotations
 
-from strix.tools.mcp.agent_tools import call_mcp, describe_mcp, list_mcps
+from strix.tools.mcp.agent_tools import (
+    call_mcp,
+    describe_mcp,
+    get_mcp_tool_schema,
+    list_mcps,
+    search_mcp_tools,
+)
 from strix.tools.mcp.client import (
     ConnectedMcpServer,
     attach_mcp_requests,
@@ -19,8 +25,10 @@ from strix.tools.mcp.naming import namespaced_tool_name
 from strix.tools.mcp.registry import (
     CALL_MCP_TOOL,
     DESCRIBE_MCP_TOOL,
+    GET_MCP_TOOL_SCHEMA_TOOL,
     MCP_DISPATCH_TOOLS,
     MCP_REGISTRY_CONTEXT_KEY,
+    SEARCH_MCP_TOOLS_TOOL,
     McpCallInfo,
     McpConnectionEntry,
     McpConnectionRequest,
@@ -35,8 +43,10 @@ from strix.tools.mcp.session import McpConnectionUnavailableError, SupervisedMcp
 __all__ = [
     "CALL_MCP_TOOL",
     "DESCRIBE_MCP_TOOL",
+    "GET_MCP_TOOL_SCHEMA_TOOL",
     "MCP_DISPATCH_TOOLS",
     "MCP_REGISTRY_CONTEXT_KEY",
+    "SEARCH_MCP_TOOLS_TOOL",
     "BearerAuth",
     "ConnectedMcpServer",
     "FailureInfo",
@@ -56,8 +66,10 @@ __all__ = [
     "classify",
     "connect_mcp_servers",
     "describe_mcp",
+    "get_mcp_tool_schema",
     "list_mcps",
     "load_user_mcp_configs",
     "namespaced_tool_name",
     "resolve_mcp_call",
+    "search_mcp_tools",
 ]

strix/tools/mcp/agent_tools.py

@@ -1,18 +1,21 @@
-"""The three generic MCP dispatch tools every agent carries.
+"""The generic MCP discovery and dispatch tools every agent carries.
 
 Under the generic-dispatch model an agent does not get one tool per MCP tool.
-It gets exactly these three and discovers connections on demand:
+It gets four primary tools and discovers connections on demand:
 
 - ``list_mcps()`` returns the connections available this run — each connection's
   id, name, description, and tool count, with no tool schemas — so the model can
   discover what it can reach without any inventory in the system prompt.
-- ``describe_mcp(connection)`` returns, as text, one connection's tools with
-  their names, descriptions, and JSON input schemas — the schemas the model
-  needs, fetched on demand instead of loaded onto every request up front.
+- ``search_mcp_tools(connection, query)`` returns a small ranked candidate set.
+- ``get_mcp_tool_schema(connection, tool)`` returns one exact input schema.
 - ``call_mcp(connection, tool, arguments)`` dispatches one call to a
   connection's tool and returns its result.
 
-All three read the per-run :class:`~strix.tools.mcp.registry.McpRegistry` from the
+``describe_mcp`` remains as a compatibility path for older prompts, but current
+agents use targeted search and one-schema lookup instead of receiving a whole
+provider catalog in one model turn.
+
+All four read the per-run :class:`~strix.tools.mcp.registry.McpRegistry` from the
 run context under :data:`~strix.tools.mcp.registry.MCP_REGISTRY_CONTEXT_KEY`. They
 are ordinary ``FunctionTool`` objects placed in the agent factory's base tool set,
 so the factory's output-bounding and disk-spill wrapping apply to their results
@@ -61,12 +64,11 @@ async def list_mcps(ctx: RunContextWrapper) -> dict[str, Any]:
     """List the MCP connections available this run, so you can discover them.
 
     Read-only. Returns one entry per connection with its ``id`` (the exact name
-    you pass to ``describe_mcp`` and ``call_mcp``), ``name``, ``description``, and
-    ``tool_count`` — no tool schemas. The three MCP tools work in order: call
-    ``list_mcps`` to discover the available connections, then ``describe_mcp`` on
-    one connection to inspect its tools and their input schemas, then ``call_mcp``
-    to run one of its tools. Returns an empty ``connections`` list when the run has
-    no MCP connections.
+    you pass to the other MCP tools), ``name``, ``description``, and
+    ``tool_count``. The response does not include tool schemas. Call
+    ``search_mcp_tools`` next. Then call ``get_mcp_tool_schema`` for one selected
+    tool before you call ``call_mcp``. Returns an empty ``connections`` list when
+    the run has no MCP connections.
     """
     registry = _registry_from_ctx(ctx)
     if registry is None or not registry:
@@ -80,6 +82,7 @@ async def list_mcps(ctx: RunContextWrapper) -> dict[str, Any]:
                 "description": summary.purpose,
                 "tool_count": summary.tool_count,
                 "dead": dead_by_name.get(summary.name, False),
+                "state": summary.state,
             }
             for summary in registry.summaries()
         ]
@@ -88,13 +91,12 @@ async def list_mcps(ctx: RunContextWrapper) -> dict[str, Any]:
 
 @function_tool(timeout=60)
 async def describe_mcp(ctx: RunContextWrapper, connection: str) -> str:
-    """List the tools one MCP connection offers, with their input schemas.
+    """Return one connection's full tool catalog as a compatibility fallback.
 
-    Read-only. Look up a connection by the id ``list_mcps`` reported for it; this
-    returns each of its tools with the tool's name, description, and JSON input
-    schema — the argument shape you pass to ``call_mcp``. Call this before
-    ``call_mcp`` on any connection you have not used yet. Nothing is fetched from
-    or run against the connection's data.
+    Read-only. This result can be large because it includes every tool schema.
+    First use ``search_mcp_tools`` and ``get_mcp_tool_schema``. Use this fallback
+    only when targeted search cannot identify an expected tool. Nothing is read
+    from the connected account.
 
     Args:
         connection: The connection name exactly as reported by ``list_mcps``.
@@ -106,7 +108,7 @@ async def describe_mcp(ctx: RunContextWrapper, connection: str) -> str:
     if entry is None:
         return _unknown_connection(connection, registry)
     try:
-        tools = await entry.session.list_tools()
+        tools = await entry.ensure_catalog()
     except McpConnectionUnavailableError as exc:
         return str(exc)
     if not tools:
@@ -116,6 +118,121 @@ async def describe_mcp(ctx: RunContextWrapper, connection: str) -> str:
     return f"{header}\n{body}"
 
 
+def _search_score(tool: MCPTool, query_terms: list[str], active: bool) -> tuple[int, str]:
+    name = tool.name.lower()
+    description = (tool.description or "").lower()
+    if not query_terms:
+        return (100 if active else 0, name)
+    score = 100 if active else 0
+    matched_terms = 0
+    for term in query_terms:
+        if name == term:
+            score += 60
+            matched_terms += 1
+        elif name.startswith(term):
+            score += 35
+            matched_terms += 1
+        elif term in name:
+            score += 25
+            matched_terms += 1
+        elif term in description:
+            score += 10
+            matched_terms += 1
+    if matched_terms == 0:
+        return (-1, name)
+    return (score + (matched_terms * 5), name)
+
+
+@function_tool(timeout=60)
+async def search_mcp_tools(
+    ctx: RunContextWrapper,
+    connection: str,
+    query: str,
+    limit: int = 8,
+) -> dict[str, Any] | str:
+    """Search one connection's tools without returning their full schemas.
+
+    The first search lazily connects the provider and caches its catalog. Results
+    contain only names, short descriptions, and whether each tool is in the
+    scan's active set. Call ``get_mcp_tool_schema`` for the selected tool.
+
+    Args:
+        connection: The connection name exactly as reported by ``list_mcps``.
+        query: Capability words such as ``page content`` or ``workspace identity``.
+        limit: Maximum candidates to return, from 1 through 20.
+    """
+    registry = _registry_from_ctx(ctx)
+    if registry is None or not registry:
+        return _NO_CONNECTIONS
+    entry = registry.get(connection)
+    if entry is None:
+        return _unknown_connection(connection, registry)
+    try:
+        tools = await entry.ensure_catalog()
+    except McpConnectionUnavailableError as exc:
+        return str(exc)
+    terms = [term for term in query.lower().split() if term]
+    bounded_limit = min(max(limit, 1), 20)
+    ranked = [
+        (score, tool)
+        for tool in tools
+        if (score := _search_score(tool, terms, tool.name in entry.active_tools))[0] >= 0
+    ]
+    if not ranked:
+        ranked = [
+            ((100, tool.name.lower()), tool) for tool in tools if tool.name in entry.active_tools
+        ]
+    ranked.sort(key=lambda item: (-item[0][0], item[0][1]))
+    return {
+        "connection": connection,
+        "query": query,
+        "matches": [
+            {
+                "name": tool.name,
+                "description": (tool.description or "").strip() or None,
+                "active": tool.name in entry.active_tools,
+            }
+            for _, tool in ranked[:bounded_limit]
+        ],
+    }
+
+
+@function_tool(timeout=60)
+async def get_mcp_tool_schema(
+    ctx: RunContextWrapper,
+    connection: str,
+    tool: str,
+) -> dict[str, Any] | str:
+    """Return one MCP tool's exact input schema.
+
+    Args:
+        connection: The connection name exactly as reported by ``list_mcps``.
+        tool: One exact tool name returned by ``search_mcp_tools``.
+    """
+    registry = _registry_from_ctx(ctx)
+    if registry is None or not registry:
+        return _NO_CONNECTIONS
+    entry = registry.get(connection)
+    if entry is None:
+        return _unknown_connection(connection, registry)
+    try:
+        tools = await entry.ensure_catalog()
+    except McpConnectionUnavailableError as exc:
+        return str(exc)
+    match = next((candidate for candidate in tools if candidate.name == tool), None)
+    if match is None:
+        return (
+            f"Unknown tool {tool!r} on MCP connection {connection!r}. "
+            "Call search_mcp_tools to find an available tool."
+        )
+    return {
+        "connection": connection,
+        "name": match.name,
+        "description": (match.description or "").strip() or None,
+        "input_schema": match.inputSchema or {"type": "object"},
+    }
+
+
 @function_tool(timeout=120, strict_mode=False)
 async def call_mcp(
     ctx: RunContextWrapper,
@@ -125,19 +242,18 @@ async def call_mcp(
 ) -> Any:
     """Call one tool on one MCP connection and return its result.
 
-    Address the tool by the connection id from ``list_mcps`` and the tool name
-    from ``describe_mcp`` on that connection. Pass the tool's arguments as an
-    object matching the input schema ``describe_mcp`` showed for it (omit it, or
-    pass an empty object, for a tool that takes no arguments).
+    Use the connection id from ``list_mcps``. Use the tool name from
+    ``search_mcp_tools``. Pass an object that matches the schema from
+    ``get_mcp_tool_schema``. Omit the arguments for a tool that takes no
+    arguments.
 
     Args:
         connection: The connection name exactly as reported by ``list_mcps``.
-        tool: The tool name, exactly as reported by ``describe_mcp``.
+        tool: The tool name exactly as reported by ``search_mcp_tools``.
         arguments: The tool's arguments as a JSON object of names to values (for
             example ``{"path": "app.py"}``), or omitted/empty for a tool that
-            takes none. Pass an object, not a stringified one. Its shape is
-            whatever ``describe_mcp`` showed for the tool rather than a shape this
-            tool fixes in advance.
+            takes none. Pass an object, not a stringified object. Match the shape
+            that ``get_mcp_tool_schema`` returned.
     """
     registry = _registry_from_ctx(ctx)
     if registry is None or not registry:
@@ -147,7 +263,7 @@ async def call_mcp(
         return _unknown_connection(connection, registry)
     invalid_arguments = (
         f"Invalid arguments for {connection!r}.{tool}: expected a JSON object of "
-        "argument names to values, or none. Call describe_mcp for the input schema."
+        "argument names to values, or none. Call get_mcp_tool_schema for the schema."
     )
     if isinstance(arguments, str):
         # The ``arguments`` parameter is schema-less (an open object is not
@@ -162,18 +278,17 @@ async def call_mcp(
     if arguments is not None and not isinstance(arguments, dict):
         return invalid_arguments
     try:
-        available = await entry.session.list_tools()
+        available = await entry.ensure_catalog()
     except McpConnectionUnavailableError as exc:
         return _errored_tool_output(str(exc))
     valid_names = {mcp_tool.name for mcp_tool in available}
     if tool not in valid_names:
-        offered = ", ".join(sorted(valid_names)) or "(none)"
         return (
             f"Unknown tool {tool!r} on MCP connection {connection!r}. "
-            f"Tools this connection offers: {offered}. "
-            "Call describe_mcp for their input schemas."
+            "Call search_mcp_tools, then get_mcp_tool_schema."
         )
-    return await entry.session.dispatch(
+    session = await entry.ensure_connected()
+    return await session.dispatch(
         tool,
         arguments or {},
         label=namespaced_tool_name(connection, tool),

strix/tools/mcp/client.py

@@ -14,6 +14,7 @@ fails the run.
 
 from __future__ import annotations
 
+import asyncio
 import contextlib
 import json
 import logging
@@ -281,8 +282,10 @@ async def _count_session_tools(config: McpConnectionConfig, session: SupervisedM
 
 async def connect_mcp_servers(
     configs: list[McpConnectionConfig],
+    *,
+    max_concurrency: int = 6,
 ) -> list[ConnectedMcpServer]:
-    """Connect each MCP config on its own supervising task and return the sessions.
+    """Connect MCP configs concurrently under a fixed bound.
 
     Each connection becomes a :class:`~strix.tools.mcp.session.SupervisedMcpSession`
     that owns ``connect()``, the held-open session, and ``cleanup()`` on one
@@ -301,41 +304,43 @@ async def connect_mcp_servers(
     :class:`~strix.tools.mcp.registry.McpRegistry` from these sessions, and the
     agent reaches each tool on demand through ``describe_mcp`` / ``call_mcp``.
     """
-    connected: list[ConnectedMcpServer] = []
+    semaphore = asyncio.Semaphore(max(1, max_concurrency))
     sessions: list[SupervisedMcpSession] = []
-    try:
-        for config in configs:
+
+    async def connect_one(config: McpConnectionConfig) -> ConnectedMcpServer | None:
+        async with semaphore:
             session = SupervisedMcpSession(config)
             sessions.append(session)
-            if not await session.start():
-                # Initial connect failed; already logged inside the session. Drop it.
-                await session.aclose()
-                sessions.remove(session)
-                continue
             try:
+                if not await session.start():
+                    await session.aclose()
+                    return None
                 tool_count = await _count_session_tools(config, session)
             except McpConnectionUnavailableError:
-                # The session died between connecting and its first listing; skip it.
                 logger.warning("MCP connection %r died before its first listing", config.name)
                 await session.aclose()
-                sessions.remove(session)
-                continue
+                return None
+            except BaseException:
+                with contextlib.suppress(BaseException):
+                    await session.aclose()
+                raise
             logger.info("Connected MCP server %r (%d tools)", config.name, tool_count)
-            connected.append(
-                ConnectedMcpServer(
-                    session=session, name=config.name, tool_count=tool_count, notes=config.notes
-                )
+            return ConnectedMcpServer(
+                session=session,
+                name=config.name,
+                tool_count=tool_count,
+                notes=config.notes,
             )
-    except BaseException:
-        # Cancelled or errored mid-attach: close every session started so far,
-        # each on its own task, then re-raise. The runner only receives the list
-        # on a clean return, so on an abnormal exit this function owns the cleanup.
-        for session in sessions:
-            with contextlib.suppress(BaseException):
-                await session.aclose()
-        raise
 
-    return connected
+    try:
+        results = await asyncio.gather(*(connect_one(config) for config in configs))
+    except BaseException:
+        await asyncio.gather(
+            *(session.aclose() for session in sessions),
+            return_exceptions=True,
+        )
+        raise
+    return [result for result in results if result is not None]
 
 
 async def attach_mcp_requests(

strix/tools/mcp/config.py

@@ -62,6 +62,9 @@ class McpConnectionConfig(BaseModel):
     """Tool allowlist, applied after the server lists its tools. ``None`` (the
     default) exposes every tool the server lists; a list restricts to it."""
 
+    active_tools: list[str] = Field(default_factory=list)
+    """Small scan-relevant subset ranked ahead of the broader allowed catalog."""
+
     notes: str | None = None
     """Free-text notes for the agent describing what this connection is and how
     to use it. When set, the note becomes the connection's purpose line in the

strix/tools/mcp/registry.py

@@ -22,13 +22,18 @@ single dispatch point.
 
 from __future__ import annotations
 
+import asyncio
+import contextlib
 import dataclasses
-from typing import TYPE_CHECKING, Any, NamedTuple
+import time
+from typing import TYPE_CHECKING, Any, Literal, NamedTuple
 
-from strix.tools.mcp.session import SupervisedMcpSession
+from strix.tools.mcp.session import McpConnectionUnavailableError, SupervisedMcpSession
 
 
 if TYPE_CHECKING:
+    from collections.abc import Callable
+
     from agents.mcp import MCPServer
 
     from strix.tools.mcp.client import ResultTransform
@@ -49,37 +54,60 @@ MCP_REGISTRY_CONTEXT_KEY = "mcp_registry"
 # tracer all recognise a connection-scoped dispatch call by the same names.
 CALL_MCP_TOOL = "call_mcp"
 DESCRIBE_MCP_TOOL = "describe_mcp"
-MCP_DISPATCH_TOOLS = frozenset({CALL_MCP_TOOL, DESCRIBE_MCP_TOOL})
+SEARCH_MCP_TOOLS_TOOL = "search_mcp_tools"
+GET_MCP_TOOL_SCHEMA_TOOL = "get_mcp_tool_schema"
+MCP_DISPATCH_TOOLS = frozenset(
+    {
+        CALL_MCP_TOOL,
+        DESCRIBE_MCP_TOOL,
+        SEARCH_MCP_TOOLS_TOOL,
+        GET_MCP_TOOL_SCHEMA_TOOL,
+    }
+)
+
+McpConnectionState = Literal[
+    "configured",
+    "connecting",
+    "connected",
+    "catalog_loading",
+    "catalog_ready",
+    "unavailable",
+]
+_RETRY_DELAY_SECONDS = 5.0
 
 
-@dataclasses.dataclass(frozen=True)
+@dataclasses.dataclass
 class McpConnectionEntry:
-    """One live MCP connection a scan may reach, keyed by ``name``.
+    """One configured MCP connection a scan may reach, keyed by ``name``.
 
-    ``session`` is the :class:`~strix.tools.mcp.session.SupervisedMcpSession` that
-    owns the connection on its own task; the dispatch tools list tools and call
-    tools through it (``session.list_tools`` / ``session.dispatch``) so a session
-    failure is contained and can reconnect. ``purpose`` is the human label
-    ``list_mcps`` reports as the connection's description (the user's connection
-    notes, or whatever the caller supplies). ``tool_count`` is how many tools the
-    connection offers, also reported by ``list_mcps``. ``result_transform``, when
-    set, runs on each call's structured result at the single dispatch point
-    (strix-pro's sanitizer uses it). ``provider`` is an optional source label
-    (e.g. ``"supabase"``) the caller tags the connection with; the command-line
-    path leaves it ``None``, and event tagging surfaces it when set.
-
-    The connection config the session reconnects with (and its bearer token) lives
-    on ``session`` in memory only. It is reached via :attr:`config` for the
-    reconnect path and is never logged, serialized into the event stream, or
-    written to disk.
+    Registration is inert. The first warm-up, search, schema lookup, or call
+    creates one shared connection task; the first catalog operation creates one
+    shared listing task. Root and child agents therefore reuse the same session
+    and catalog even when they request a cold connection concurrently.
     """
 
-    session: SupervisedMcpSession
     name: str
+    connection_config: McpConnectionConfig | None = dataclasses.field(
+        default=None,
+        repr=False,
+    )
+    session: SupervisedMcpSession | None = dataclasses.field(default=None, repr=False)
     purpose: str | None = None
     tool_count: int = 0
     result_transform: ResultTransform | None = None
     provider: str | None = None
+    state: McpConnectionState = "configured"
+    _catalog: list[Any] | None = dataclasses.field(default=None, repr=False)
+    _connect_task: asyncio.Task[SupervisedMcpSession] | None = dataclasses.field(
+        default=None,
+        repr=False,
+    )
+    _catalog_task: asyncio.Task[list[Any]] | None = dataclasses.field(
+        default=None,
+        repr=False,
+    )
+    _retry_after: float = dataclasses.field(default=0.0, repr=False)
+    _status_sink: Callable[[], None] | None = dataclasses.field(default=None, repr=False)
 
     @property
     def server(self) -> MCPServer | None:
@@ -88,12 +116,143 @@ class McpConnectionEntry:
         Kept so existing callers that read ``entry.server`` keep working; new code
         should call through ``entry.session`` so reconnect and containment apply.
         """
-        return self.session.server
+        return self.session.server if self.session is not None else None
 
     @property
     def config(self) -> McpConnectionConfig | None:
-        """The session's reconnect config. Carries the bearer token; never log it."""
-        return self.session.config
+        """The reconnect config. Carries the bearer token; never log it."""
+        if self.connection_config is not None:
+            return self.connection_config
+        return self.session.config if self.session is not None else None
+
+    @property
+    def active_tools(self) -> frozenset[str]:
+        config = self.config
+        return frozenset(config.active_tools if config is not None else ())
+
+    def set_status_sink(self, sink: Callable[[], None] | None) -> None:
+        self._status_sink = sink
+        if self.session is not None:
+            self.session.set_on_dead(self._on_dead)
+
+    def _set_state(self, state: McpConnectionState) -> None:
+        if self.state == state:
+            return
+        self.state = state
+        if self._status_sink is not None:
+            self._status_sink()
+
+    def _on_dead(self) -> None:
+        self.session = None
+        self._catalog = None
+        self._catalog_task = None
+        self._retry_after = time.monotonic() + _RETRY_DELAY_SECONDS
+        self._set_state("unavailable")
+
+    async def ensure_connected(self) -> SupervisedMcpSession:
+        """Return this entry's live session, connecting it once when needed."""
+        if self.session is not None:
+            return self.session
+        if self.connection_config is None:
+            raise McpConnectionUnavailableError(
+                f"MCP connection {self.name!r} is unavailable and cannot reconnect."
+            )
+        if self._connect_task is None:
+            if self.state == "unavailable" and time.monotonic() < self._retry_after:
+                raise McpConnectionUnavailableError(
+                    f"MCP connection {self.name!r} is temporarily unavailable."
+                )
+            self._connect_task = asyncio.create_task(
+                self._connect(),
+                name=f"mcp-connect-{self.name}",
+            )
+        task = self._connect_task
+        try:
+            return await asyncio.shield(task)
+        finally:
+            if self._connect_task is task and task.done():
+                self._connect_task = None
+
+    async def _connect(self) -> SupervisedMcpSession:
+        config = self.connection_config
+        if config is None:
+            raise McpConnectionUnavailableError(
+                f"MCP connection {self.name!r} has no connection configuration."
+            )
+        self._set_state("connecting")
+        session = SupervisedMcpSession(config)
+        try:
+            started = await session.start()
+        except BaseException:
+            with contextlib.suppress(BaseException):
+                await session.aclose()
+            self._retry_after = time.monotonic() + _RETRY_DELAY_SECONDS
+            self._set_state("unavailable")
+            raise
+        if not started:
+            await session.aclose()
+            self._retry_after = time.monotonic() + _RETRY_DELAY_SECONDS
+            self._set_state("unavailable")
+            raise McpConnectionUnavailableError(f"MCP connection {self.name!r} could not connect.")
+        self.session = session
+        session.set_on_dead(self._on_dead)
+        self._retry_after = 0.0
+        self._set_state("connected")
+        return session
+
+    async def ensure_catalog(self) -> list[Any]:
+        """Return the filtered catalog, listing it once on first use."""
+        if (
+            self._catalog is not None
+            and self.session is not None
+            and not self.session.is_dead
+            and not self.session.is_unavailable
+        ):
+            return self._catalog
+        if self.session is not None and (self.session.is_dead or self.session.is_unavailable):
+            self._catalog = None
+        if self._catalog_task is None:
+            self._catalog_task = asyncio.create_task(
+                self._load_catalog(),
+                name=f"mcp-catalog-{self.name}",
+            )
+        task = self._catalog_task
+        try:
+            return await asyncio.shield(task)
+        finally:
+            if self._catalog_task is task and task.done():
+                self._catalog_task = None
+
+    async def _load_catalog(self) -> list[Any]:
+        session = await self.ensure_connected()
+        self._set_state("catalog_loading")
+        try:
+            catalog = await session.list_tools()
+        except BaseException:
+            if session.is_dead:
+                self._set_state("unavailable")
+            else:
+                self._set_state("connected")
+            raise
+        self._catalog = list(catalog)
+        self.tool_count = len(self._catalog)
+        self._set_state("catalog_ready")
+        return self._catalog
+
+    async def close(self) -> None:
+        """Cancel pending initialization and close an opened session."""
+        tasks = [task for task in (self._catalog_task, self._connect_task) if task is not None]
+        for task in tasks:
+            task.cancel()
+        for task in tasks:
+            with contextlib.suppress(BaseException):
+                await task
+        self._catalog_task = None
+        self._connect_task = None
+        if self.session is not None:
+            with contextlib.suppress(BaseException):
+                await self.session.aclose()
+        self.session = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -105,6 +264,7 @@ class McpConnectionSummary:
     purpose: str | None
     tool_count: int
     provider: str | None = None
+    state: McpConnectionState = "configured"
 
 
 @dataclasses.dataclass(frozen=True)
@@ -123,6 +283,7 @@ class McpConnectionStatus:
     provider: str | None
     tool_count: int
     dead: bool
+    state: McpConnectionState
 
 
 @dataclasses.dataclass(frozen=True)
@@ -165,6 +326,21 @@ class McpRegistry:
 
     def __init__(self) -> None:
         self._entries: dict[str, McpConnectionEntry] = {}
+        self._status_sink: Callable[[], None] | None = None
+        self._warmup_task: asyncio.Task[None] | None = None
+
+    def register(self, request: McpConnectionRequest) -> McpConnectionEntry:
+        """Register an inert request without opening a network connection."""
+        entry = McpConnectionEntry(
+            name=request.config.name,
+            connection_config=request.config,
+            purpose=request.purpose or request.config.notes,
+            result_transform=request.result_transform,
+            provider=request.provider,
+        )
+        entry.set_status_sink(self._status_sink)
+        self._entries[entry.name] = entry
+        return entry
 
     def add(
         self,
@@ -191,13 +367,16 @@ class McpRegistry:
                 raise ValueError("McpRegistry.add requires either 'session' or 'server'")
             session = SupervisedMcpSession.adopt(server, name=name, config=config)
         entry = McpConnectionEntry(
-            session=session,
             name=name,
+            connection_config=config or session.config,
+            session=session,
             purpose=purpose,
             tool_count=tool_count,
             result_transform=result_transform,
             provider=provider,
+            state="connected",
         )
+        entry.set_status_sink(self._status_sink)
         self._entries[name] = entry
         return entry
 
@@ -217,6 +396,7 @@ class McpRegistry:
                 purpose=entry.purpose,
                 tool_count=entry.tool_count,
                 provider=entry.provider,
+                state=entry.state,
             )
             for entry in self._entries.values()
         ]
@@ -233,7 +413,9 @@ class McpRegistry:
                 name=entry.name,
                 provider=entry.provider,
                 tool_count=entry.tool_count,
-                dead=entry.session.is_dead,
+                dead=entry.state == "unavailable"
+                or (entry.session is not None and entry.session.is_dead),
+                state=entry.state,
             )
             for entry in self._entries.values()
         ]
@@ -243,6 +425,42 @@ class McpRegistry:
         runner)."""
         self._entries.clear()
 
+    def set_status_sink(self, sink: Callable[[], None] | None) -> None:
+        """Receive a callback after any connection lifecycle transition."""
+        self._status_sink = sink
+        for entry in self._entries.values():
+            entry.set_status_sink(sink)
+
+    def start_warmup(self, *, max_concurrency: int = 6) -> asyncio.Task[None]:
+        """Connect every configured entry in the background with a fixed bound."""
+        if self._warmup_task is not None:
+            return self._warmup_task
+
+        async def warm() -> None:
+            semaphore = asyncio.Semaphore(max(1, max_concurrency))
+
+            async def connect(entry: McpConnectionEntry) -> None:
+                async with semaphore:
+                    with contextlib.suppress(McpConnectionUnavailableError):
+                        await entry.ensure_connected()
+
+            await asyncio.gather(*(connect(entry) for entry in self._entries.values()))
+
+        self._warmup_task = asyncio.create_task(warm(), name="mcp-warmup")
+        return self._warmup_task
+
+    async def close(self) -> None:
+        """Stop warm-up and close only sessions this registry opened."""
+        if self._warmup_task is not None:
+            self._warmup_task.cancel()
+            with contextlib.suppress(BaseException):
+                await self._warmup_task
+            self._warmup_task = None
+        await asyncio.gather(
+            *(entry.close() for entry in self._entries.values()),
+            return_exceptions=True,
+        )
+
     def __len__(self) -> int:
         return len(self._entries)
 
@@ -282,6 +500,6 @@ def resolve_mcp_call(
         if entry is None:
             return None
         provider = entry.provider
-    raw_tool = args.get("tool") if tool_name == CALL_MCP_TOOL else ""
+    raw_tool = args.get("tool") if tool_name in {CALL_MCP_TOOL, GET_MCP_TOOL_SCHEMA_TOOL} else ""
     tool = raw_tool if isinstance(raw_tool, str) else ""
     return McpCallInfo(connection=connection, tool=tool, provider=provider)

tests/test_disable_streaming.py

@@ -32,6 +32,7 @@ from openai.types.responses import (
 from strix.config import codex, loader
 from strix.config.loader import load_settings
 from strix.config.models import StrixProvider, _NonStreamingModel, _TurnGuardModel
+from strix.llm.request_log import RequestLoggingModel
 
 
 if TYPE_CHECKING:
@@ -312,7 +313,8 @@ def test_get_model_keeps_streaming_by_default(
 
     model = StrixProvider().get_model("openai/gpt-4o-mini")
     assert isinstance(model, _TurnGuardModel)
-    assert model._inner is inner
+    assert isinstance(model._inner, RequestLoggingModel)
+    assert model._inner._inner is inner
 
 
 def test_get_model_guards_subscription_model_but_keeps_it_streaming(

tests/test_execution_request_log.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, cast
+
+import httpx
+import pytest
+from agents import RunConfig, Runner
+from openai import APIError, PermissionDeniedError
+
+from strix.core import execution
+from strix.core.agents import AgentCoordinator
+from strix.llm import request_log
+
+
+if TYPE_CHECKING:
+    from collections.abc import AsyncIterator
+
+
+def _request() -> httpx.Request:
+    return httpx.Request("POST", "https://api.openai.com/v1/responses")
+
+
+def _midstream_api_error() -> APIError:
+    return APIError("An error occurred while processing the request.", _request(), body=None)
+
+
+def _blocked_error() -> PermissionDeniedError:
+    response = httpx.Response(
+        403, request=_request(), headers={"x-request-id": "req_blocked_hdr"}, text="blocked"
+    )
+    return PermissionDeniedError("Output blocked by policy", response=response, body=None)
+
+
+class _FakeStream:
+    def __init__(self, exc: BaseException | None = None) -> None:
+        self._exc = exc
+        self.run_loop_exception: BaseException | None = None
+        self.seen_context: request_log.LlmCallContext | None = None
+
+    async def stream_events(self) -> AsyncIterator[Any]:
+        self.seen_context = request_log.current_call_context()
+        if self._exc is not None:
+            raise self._exc
+        items: tuple[Any, ...] = ()
+        for item in items:
+            yield item
+
+
+async def _run(
+    monkeypatch: pytest.MonkeyPatch,
+    streams: list[_FakeStream],
+    coordinator: AgentCoordinator | None = None,
+) -> Any:
+    monkeypatch.setattr(execution, "_TRANSIENT_MODEL_RETRY_BASE_DELAY_S", 0.0)
+    monkeypatch.setattr(execution, "_TRANSIENT_MODEL_RETRY_MAX_DELAY_S", 0.0)
+    calls = {"n": 0}
+
+    def _fake_run_streamed(*_args: Any, **_kwargs: Any) -> _FakeStream:
+        stream = streams[calls["n"]]
+        calls["n"] += 1
+        return stream
+
+    monkeypatch.setattr(Runner, "run_streamed", _fake_run_streamed)
+    coordinator = coordinator or AgentCoordinator()
+    await coordinator.register("root", "strix", parent_id=None)
+    return await execution._run_cycle(
+        object(),
+        coordinator,
+        "root",
+        input_data="task",
+        run_config=cast("RunConfig", object()),
+        context={},
+        max_turns=5,
+        session=None,
+        interactive=False,
+        event_sink=None,
+        hooks=None,
+    )
+
+
+@pytest.mark.asyncio
+async def test_each_transient_replay_is_stamped_with_its_attempt_number(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    streams = [
+        _FakeStream(exc=_midstream_api_error()),
+        _FakeStream(exc=_midstream_api_error()),
+        _FakeStream(),
+    ]
+    await _run(monkeypatch, streams)
+    assert [s.seen_context.retry_attempt for s in streams if s.seen_context] == [0, 1, 2]
+
+
+@pytest.mark.asyncio
+async def test_blocked_provider_failure_text_carries_request_id(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    coordinator = AgentCoordinator()
+    with pytest.raises(PermissionDeniedError):
+        await _run(monkeypatch, [_FakeStream(exc=_blocked_error())], coordinator)
+    assert coordinator.statuses["root"] == "failed"
+    error = coordinator.errors["root"]
+    assert "Output blocked by policy" in error
+    assert error.endswith("[provider request id: req_blocked_hdr]")
+
+
+@pytest.mark.asyncio
+async def test_run_agent_loop_binds_agent_context_and_resets(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    seen: dict[str, request_log.LlmCallContext] = {}
+
+    async def _fake_loop(**_kwargs: Any) -> None:
+        seen["ctx"] = request_log.current_call_context()
+
+    monkeypatch.setattr(execution, "_run_agent_loop", _fake_loop)
+
+    class _Agent:
+        name = "Recon Agent"
+
+    coordinator = AgentCoordinator()
+    await execution.run_agent_loop(
+        agent=_Agent(),
+        initial_input="task",
+        run_config=cast("RunConfig", object()),
+        context={},
+        max_turns=1,
+        coordinator=coordinator,
+        agent_id="agent-42",
+        interactive=False,
+    )
+    assert seen["ctx"].agent_id == "agent-42"
+    assert seen["ctx"].agent_name == "Recon Agent"
+    assert request_log.current_call_context().agent_id is None

tests/test_mcp_client.py

@@ -36,12 +36,15 @@ from strix.tools.mcp import (
     attach_mcp_requests,
     call_mcp,
     describe_mcp,
+    get_mcp_tool_schema,
     list_mcps,
     load_user_mcp_configs,
     namespaced_tool_name,
     resolve_mcp_call,
+    search_mcp_tools,
 )
 from strix.tools.mcp import client as mcp_client
+from strix.tools.mcp import registry as mcp_registry_mod
 from strix.tools.mcp import session as mcp_session_mod
 
 
@@ -434,8 +437,16 @@ async def test_list_mcps_returns_connections_with_ids_and_descriptions() -> None
                 "description": "local files",
                 "tool_count": 2,
                 "dead": False,
+                "state": "connected",
+            },
+            {
+                "id": "db",
+                "name": "db",
+                "description": None,
+                "tool_count": 1,
+                "dead": False,
+                "state": "connected",
             },
-            {"id": "db", "name": "db", "description": None, "tool_count": 1, "dead": False},
         ]
     }
 
@@ -485,6 +496,247 @@ async def test_describe_mcp_without_any_connections() -> None:
     assert out == "No MCP connections are configured for this run."
 
 
+@pytest.mark.asyncio
+async def test_search_then_get_one_schema_without_returning_other_schemas() -> None:
+    registry = McpRegistry()
+    registry.add(
+        name="docs",
+        server=FakeMCPServer(
+            "docs",
+            [
+                _mcp_tool("find_pages"),
+                MCPTool(
+                    name="fetch_page",
+                    description="Fetch page content",
+                    inputSchema={
+                        "type": "object",
+                        "properties": {"page_id": {"type": "string"}},
+                    },
+                ),
+            ],
+        ),
+        config=McpConnectionConfig(
+            name="docs",
+            url="https://example.invalid/mcp",
+            active_tools=["fetch_page"],
+        ),
+    )
+
+    searched = await search_mcp_tools.on_invoke_tool(
+        _ctx(registry),
+        json.dumps({"connection": "docs", "query": "page content"}),
+    )
+    assert [match["name"] for match in searched["matches"]] == [
+        "fetch_page",
+        "find_pages",
+    ]
+    assert all("input_schema" not in match for match in searched["matches"])
+
+    schema = await get_mcp_tool_schema.on_invoke_tool(
+        _ctx(registry),
+        json.dumps({"connection": "docs", "tool": "fetch_page"}),
+    )
+    assert schema["input_schema"]["properties"] == {"page_id": {"type": "string"}}
+
+
+@pytest.mark.asyncio
+async def test_search_matches_any_query_term_and_prioritizes_active_tools() -> None:
+    registry = McpRegistry()
+    registry.add(
+        name="docs",
+        server=FakeMCPServer(
+            "docs",
+            [
+                MCPTool(
+                    name="fetch_page",
+                    description="Read page content",
+                    inputSchema={"type": "object"},
+                ),
+                MCPTool(
+                    name="search_documents",
+                    description="Search documents",
+                    inputSchema={"type": "object"},
+                ),
+                MCPTool(
+                    name="list_records",
+                    description="List records",
+                    inputSchema={"type": "object"},
+                ),
+            ],
+        ),
+        config=McpConnectionConfig(
+            name="docs",
+            url="https://example.invalid/mcp",
+            active_tools=["fetch_page"],
+        ),
+    )
+
+    searched = await search_mcp_tools.on_invoke_tool(
+        _ctx(registry),
+        json.dumps(
+            {
+                "connection": "docs",
+                "query": "read list search document",
+            }
+        ),
+    )
+
+    assert [match["name"] for match in searched["matches"]] == [
+        "fetch_page",
+        "search_documents",
+        "list_records",
+    ]
+
+
+@pytest.mark.asyncio
+async def test_search_returns_active_tools_when_text_does_not_match() -> None:
+    registry = McpRegistry()
+    registry.add(
+        name="docs",
+        server=FakeMCPServer(
+            "docs",
+            [
+                _mcp_tool("fetch_page"),
+                _mcp_tool("search_documents"),
+            ],
+        ),
+        config=McpConnectionConfig(
+            name="docs",
+            url="https://example.invalid/mcp",
+            active_tools=["fetch_page"],
+        ),
+    )
+
+    searched = await search_mcp_tools.on_invoke_tool(
+        _ctx(registry),
+        json.dumps(
+            {
+                "connection": "docs",
+                "query": "unrelated capability",
+            }
+        ),
+    )
+
+    assert searched["matches"] == [
+        {
+            "name": "fetch_page",
+            "description": "remote tool fetch_page",
+            "active": True,
+        }
+    ]
+
+
+@pytest.mark.asyncio
+async def test_registered_entry_connects_and_lists_once_for_concurrent_catalog_requests(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    calls = {"build": 0, "list": 0}
+
+    class _CountingServer(FakeMCPServer):
+        async def list_tools(
+            self,
+            run_context: Any = None,
+            agent: Any = None,
+        ) -> list[MCPTool]:
+            calls["list"] += 1
+            await asyncio.sleep(0)
+            return await super().list_tools(run_context, agent)
+
+    server = _CountingServer("docs", [_mcp_tool("fetch_page")])
+
+    def _build(_config: McpConnectionConfig) -> mcp_client.BuiltMcpServer:
+        calls["build"] += 1
+        return _built_server(server)
+
+    monkeypatch.setattr(mcp_client, "_build_server", _build)
+    registry = McpRegistry()
+    entry = registry.register(McpConnectionRequest(config=_config("docs", ["fetch_page"])))
+    assert entry.state == "configured"
+    assert calls == {"build": 0, "list": 0}
+
+    first, second = await asyncio.gather(entry.ensure_catalog(), entry.ensure_catalog())
+
+    assert [tool.name for tool in first] == ["fetch_page"]
+    assert second is first
+    assert calls == {"build": 1, "list": 1}
+    assert registry.statuses()[0].state == "catalog_ready"
+    await registry.close()
+
+
+@pytest.mark.asyncio
+async def test_registered_entry_replaces_a_terminally_dead_session(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    config = _config("docs", ["fetch_page"])
+    original = SupervisedMcpSession.adopt(
+        FakeMCPServer("docs", [_mcp_tool("fetch_page")]),
+        name="docs",
+        config=config,
+    )
+    replacement_server = FakeMCPServer("docs", [_mcp_tool("fetch_page")])
+    monkeypatch.setattr(
+        mcp_client,
+        "_build_server",
+        lambda _config: _built_server(replacement_server),
+    )
+    monkeypatch.setattr(mcp_registry_mod, "_RETRY_DELAY_SECONDS", 0)
+    registry = McpRegistry()
+    entry = registry.add(name="docs", session=original, config=config)
+
+    original._mark_dead()
+
+    assert entry.session is None
+    replacement = await entry.ensure_connected()
+    assert replacement is not original
+    assert replacement.server is replacement_server
+    assert entry.state == "connected"
+    await registry.close()
+
+
+@pytest.mark.asyncio
+async def test_registry_warmup_bounds_parallel_connections(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    active = 0
+    maximum = 0
+    two_started = asyncio.Event()
+    release = asyncio.Event()
+
+    class _BlockedConnectServer(FakeMCPServer):
+        async def connect(self) -> None:
+            nonlocal active, maximum
+            active += 1
+            maximum = max(maximum, active)
+            if active == 2:
+                two_started.set()
+            try:
+                await release.wait()
+            finally:
+                active -= 1
+
+    servers = {
+        f"docs-{index}": _BlockedConnectServer(f"docs-{index}", [_mcp_tool("fetch_page")])
+        for index in range(4)
+    }
+    monkeypatch.setattr(
+        mcp_client,
+        "_build_server",
+        lambda config: _built_server(servers[config.name]),
+    )
+    registry = McpRegistry()
+    for name in servers:
+        registry.register(McpConnectionRequest(config=_config(name, ["fetch_page"])))
+
+    warmup = registry.start_warmup(max_concurrency=2)
+    await asyncio.wait_for(two_started.wait(), timeout=1)
+    assert maximum == 2
+    release.set()
+    await warmup
+
+    assert [summary.state for summary in registry.summaries()] == ["connected"] * 4
+    await registry.close()
+
+
 # --- call_mcp ----------------------------------------------------------------
 
 
@@ -573,7 +825,8 @@ async def test_call_mcp_errors_on_unknown_tool() -> None:
     )
 
     assert "Unknown tool 'delete_everything'" in out
-    assert "read_file" in out
+    assert "search_mcp_tools" in out
+    assert "read_file" not in out
     # A rejected tool name never reaches the server.
     assert server.calls == []
 
@@ -631,21 +884,27 @@ async def test_call_mcp_flags_an_errored_result_failed_for_the_tui() -> None:
     assert out == {"type": "text", "text": "boom:read_file", "success": False}
 
 
-# --- the two tools are the only MCP surface every agent gets -----------------
+# --- generic MCP tools are the only MCP surface every agent gets -------------
 
 
-def test_agent_carries_exactly_the_dispatch_tools_regardless_of_connections() -> None:
+def test_agent_carries_exactly_the_generic_mcp_tools_regardless_of_connections() -> None:
     """No matter how many MCP connections a run makes, an agent's tool list gains
-    exactly list_mcps, describe_mcp, and call_mcp and never a per-connection
-    provider tool."""
+    exactly the generic MCP tools and never a per-connection provider tool."""
     root = factory.build_strix_agent(is_root=True)
     child = factory.build_strix_agent(is_root=False)
 
     root_names = [t.name for t in root.tools]
     child_names = [t.name for t in child.tools]
 
-    assert {"list_mcps", "describe_mcp", "call_mcp"} <= set(root_names)
-    assert {"list_mcps", "describe_mcp", "call_mcp"} <= set(child_names)
+    expected = {
+        "list_mcps",
+        "search_mcp_tools",
+        "get_mcp_tool_schema",
+        "describe_mcp",
+        "call_mcp",
+    }
+    assert expected <= set(root_names)
+    assert expected <= set(child_names)
 
     # Five hypothetical connections would once have added ~all their tools as
     # namespaced provider tools; none of those names may appear now.
@@ -666,16 +925,25 @@ def test_agent_carries_exactly_the_dispatch_tools_regardless_of_connections() ->
 # --- prompt guidance replaces the old per-connection inventory ---------------
 
 
-def test_prompt_renders_static_three_tool_guidance_when_mcp_available() -> None:
+def test_prompt_renders_targeted_tool_guidance_when_mcp_available() -> None:
     prompt = render_system_prompt(system_prompt_context={"mcp_available": True})
 
     assert "MCP CONNECTIONS" in prompt
-    # The three discovery/dispatch tools are named as the way in.
+    # Targeted discovery, one-schema lookup, dispatch, and compatibility are named.
     assert "list_mcps" in prompt
+    assert "search_mcp_tools" in prompt
+    assert "get_mcp_tool_schema" in prompt
     assert "describe_mcp" in prompt
     assert "call_mcp" in prompt
 
 
+def test_model_facing_mcp_guidance_uses_targeted_discovery() -> None:
+    assert "describe_mcp" not in list_mcps.description
+    assert "describe_mcp" not in call_mcp.description
+    assert "full tool catalog" in describe_mcp.description
+    assert "compatibility fallback" in describe_mcp.description
+
+
 def test_prompt_has_no_mcp_section_without_availability() -> None:
     assert "MCP CONNECTIONS" not in render_system_prompt(system_prompt_context={})
 
@@ -683,7 +951,7 @@ def test_prompt_has_no_mcp_section_without_availability() -> None:
 def test_prompt_renders_named_connection_inventory() -> None:
     """With mcp_available set, the prompt names each connected server (name, tool
     count, purpose) so every agent sees what is available at the start, alongside
-    the three dispatch tools for re-listing and inspecting them at run time."""
+    the discovery and dispatch tools for re-listing and inspecting them at run time."""
     prompt = render_system_prompt(
         system_prompt_context={
             "mcp_available": True,

tests/test_models.py

@@ -23,6 +23,7 @@ from strix.config.models import (
     uses_chat_completions_tool_schema,
 )
 from strix.config.settings import Settings
+from strix.llm.request_log import RequestLoggingModel
 
 
 @pytest.mark.parametrize("model_name", RECOMMENDED_MODEL_NAMES)
@@ -172,7 +173,7 @@ def test_routes_through_litellm_matches_the_provider(
         # proves the route is not LiteLLM's.
         assert not litellm
         return
-    while isinstance(model, _NonStreamingModel | _TurnGuardModel):
+    while isinstance(model, _NonStreamingModel | _TurnGuardModel | RequestLoggingModel):
         model = model._inner
     assert isinstance(model, LitellmModel) is litellm
 
@@ -215,6 +216,6 @@ def test_api_type_overrides_the_api_base_route(
         monkeypatch.setenv("STRIX_API_TYPE", api_type)
     configure_sdk_model_defaults(Settings())
     model = StrixProvider().get_model("gpt-5")
-    while isinstance(model, _NonStreamingModel | _TurnGuardModel):
+    while isinstance(model, _NonStreamingModel | _TurnGuardModel | RequestLoggingModel):
         model = model._inner
     assert isinstance(model, expected)

tests/test_runner_mcp.py

@@ -80,13 +80,14 @@ async def test_none_default_attaches_from_the_user_config_file(
     )
     monkeypatch.setattr(mcp_pkg, "load_user_mcp_configs", lambda: [file_config])
 
-    captured: list[list[McpConnectionRequest]] = []
+    captured: list[McpConnectionRequest] = []
+    original_register = mcp_pkg.McpRegistry.register
 
-    async def _capture(requests: list[McpConnectionRequest], _registry: Any) -> list[Any]:
-        captured.append(requests)
-        return []
+    def _capture(registry: Any, request: McpConnectionRequest) -> Any:
+        captured.append(request)
+        return original_register(registry, request)
 
-    monkeypatch.setattr(mcp_pkg, "attach_mcp_requests", _capture)
+    monkeypatch.setattr(mcp_pkg.McpRegistry, "register", _capture)
 
     await runner.run_strix_scan(
         scan_config={"targets": [], "scan_mode": "deep"},
@@ -97,12 +98,11 @@ async def test_none_default_attaches_from_the_user_config_file(
 
     # Each config from the file is wrapped in a bare request: no provider, no
     # transform, no explicit purpose (purpose falls back to notes at attach time).
-    (requests,) = captured
-    assert len(requests) == 1
-    assert requests[0].config is file_config
-    assert requests[0].provider is None
-    assert requests[0].result_transform is None
-    assert requests[0].purpose is None
+    (request,) = captured
+    assert request.config is file_config
+    assert request.provider is None
+    assert request.result_transform is None
+    assert request.purpose is None
 
 
 @pytest.mark.asyncio
@@ -116,13 +116,14 @@ async def test_supplied_requests_are_attached_and_the_user_file_is_not_read(
 
     monkeypatch.setattr(mcp_pkg, "load_user_mcp_configs", _fail_if_read)
 
-    captured: list[list[McpConnectionRequest]] = []
+    captured: list[McpConnectionRequest] = []
+    original_register = mcp_pkg.McpRegistry.register
 
-    async def _capture(requests: list[McpConnectionRequest], _registry: Any) -> list[Any]:
-        captured.append(requests)
-        return []
+    def _capture(registry: Any, request: McpConnectionRequest) -> Any:
+        captured.append(request)
+        return original_register(registry, request)
 
-    monkeypatch.setattr(mcp_pkg, "attach_mcp_requests", _capture)
+    monkeypatch.setattr(mcp_pkg.McpRegistry, "register", _capture)
 
     supplied = [
         McpConnectionRequest(
@@ -139,7 +140,7 @@ async def test_supplied_requests_are_attached_and_the_user_file_is_not_read(
         mcp_connection_requests=supplied,
     )
 
-    assert captured == [supplied]
+    assert captured == supplied
 
 
 @pytest.mark.asyncio
@@ -147,8 +148,8 @@ async def test_roster_is_persisted_even_without_a_status_sink(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Any
 ) -> None:
     """The viewer reads the roster off disk, so persistence must not depend on the
-    interface status sink: with ``mcp_status_sink=None`` the connect-time roster is
-    still written, carrying only the non-secret name/provider/tool_count/dead."""
+    interface status sink: with ``mcp_status_sink=None`` the configured roster is
+    still written, carrying only non-secret lifecycle fields."""
     _wire_runner(monkeypatch, tmp_path)
     monkeypatch.setattr(
         mcp_pkg,
@@ -156,19 +157,6 @@ async def test_roster_is_persisted_even_without_a_status_sink(
         lambda: [McpConnectionConfig(name="local_fs", transport="stdio", command="npx")],
     )
 
-    class _FakeSession:
-        is_dead = False
-
-        def set_on_dead(self, _callback: Any) -> None:
-            return None
-
-    async def _attach(_requests: list[McpConnectionRequest], registry: Any) -> list[Any]:
-        registry.add(name="local_fs", session=_FakeSession(), tool_count=3, provider=None)
-        entry = registry.get("local_fs")
-        return [types.SimpleNamespace(name="local_fs", tool_count=3, session=entry.session)]
-
-    monkeypatch.setattr(mcp_pkg, "attach_mcp_requests", _attach)
-
     persisted: list[list[dict[str, Any]]] = []
 
     def _capture_persist(roster: list[dict[str, Any]]) -> None:
@@ -185,4 +173,12 @@ async def test_roster_is_persisted_even_without_a_status_sink(
     )
 
     assert persisted, "roster must persist even when no status sink is attached"
-    assert persisted[-1] == [{"name": "local_fs", "provider": None, "tool_count": 3, "dead": False}]
+    assert persisted[0] == [
+        {
+            "name": "local_fs",
+            "provider": None,
+            "tool_count": 0,
+            "dead": False,
+            "state": "configured",
+        }
+    ]

tests/test_runner_root_prompt.py

@@ -194,21 +194,12 @@ async def test_mcp_available_flag_set_when_a_connection_attaches(
     scope_context: dict[str, Any] = {"scope": "built-in"}
     captured = _patch_engine_scaffold(monkeypatch, tmp_path, scope_context)
 
-    async def _aclose() -> None:
-        return None
-
-    async def _attach(_requests: Any, registry: Any) -> list[Any]:
-        registry.add(name="fs", server=object(), purpose="local files", tool_count=2)
-        session = types.SimpleNamespace(aclose=_aclose)
-        return [types.SimpleNamespace(name="fs", tool_count=2, session=session)]
-
-    monkeypatch.setattr(mcp_pkg, "attach_mcp_requests", _attach)
-
     request = McpConnectionRequest(
         config=McpConnectionConfig(
             name="fs",
             url="https://mcp.example.com",
             auth=BearerAuth(token="run-token"),
+            notes="local files",
         )
     )
 
@@ -224,7 +215,7 @@ async def test_mcp_available_flag_set_when_a_connection_attaches(
     assert kwargs["system_prompt_context"]["mcp_available"] is True
     # The named inventory names each connected server for the prompt.
     assert kwargs["system_prompt_context"]["mcp_connections"] == [
-        {"name": "fs", "purpose": "local files", "tool_count": 2}
+        {"name": "fs", "purpose": "local files", "tool_count": 0}
     ]
 
 

tests/test_tool_call_ids.py

@@ -1,11 +1,12 @@
-"""Tests for tool-call id uniqueness.
+"""Tests for tool-call id presence and uniqueness.
 
 Providers that number tool calls per turn (``exec_command:0``, ``:1``, ...)
 restart the counter on every turn, so the same id eventually appears twice in
-one conversation. Strict providers then reject the whole request, and because
-the history is replayed on every retry the agent can never recover. A gateway
-that validates id uniqueness the way those providers do proves both the
-failure and the fix.
+one conversation. Others hand back a tool call with no id at all, leaving the
+paired tool message with a blank ``tool_call_id``. Strict providers reject the
+whole request either way, and because the history is replayed on every retry
+the agent can never recover. Gateways that validate ids the way those
+providers do prove both failures and their fixes.
 """
 
 from __future__ import annotations
@@ -125,10 +126,51 @@ class _StrictHandler(BaseHTTPRequestHandler):
         self.wfile.write(encoded)
 
 
-@pytest.fixture
-def strict_gateway() -> Iterator[str]:
+class _BlankIdHandler(BaseHTTPRequestHandler):
+    """Gateway that hands out an id-less tool call and rejects blank ids, like GLM does."""
+
+    def log_message(self, *args: Any) -> None:
+        pass
+
+    def do_POST(self) -> None:
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length) or b"{}")
+        messages = body.get("messages", [])
+        _REQUESTS.append(messages)
+
+        for index, message in enumerate(messages):
+            if message.get("role") == "tool" and not message.get("tool_call_id"):
+                self._respond(
+                    400,
+                    {
+                        "error": {
+                            "message": (
+                                f"messages[{index}]: tool messages must include "
+                                "a non-empty string tool_call_id"
+                            ),
+                            "code": 400,
+                        }
+                    },
+                )
+                return
+
+        if len(_REQUESTS) == 1:
+            self._respond(200, _tool_call_completion(""))
+        else:
+            self._respond(200, _text_completion("all done"))
+
+    def _respond(self, status: int, payload: dict[str, Any]) -> None:
+        encoded = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+
+def _serve(handler: type[BaseHTTPRequestHandler]) -> Iterator[str]:
     _REQUESTS.clear()
-    server = HTTPServer(("127.0.0.1", 0), _StrictHandler)
+    server = HTTPServer(("127.0.0.1", 0), handler)
     thread = threading.Thread(target=server.serve_forever, daemon=True)
     thread.start()
     try:
@@ -138,6 +180,16 @@ def strict_gateway() -> Iterator[str]:
         server.server_close()
 
 
+@pytest.fixture
+def strict_gateway() -> Iterator[str]:
+    yield from _serve(_StrictHandler)
+
+
+@pytest.fixture
+def blank_id_gateway() -> Iterator[str]:
+    yield from _serve(_BlankIdHandler)
+
+
 def _model(base_url: str) -> Model:
     # The gateway answers plain JSON, so the run loop's streamed turns are
     # served non-streamed; the ids on the wire are the same either way.
@@ -222,6 +274,61 @@ def test_history_dedupe_pairs_parallel_calls_by_order() -> None:
     assert rebuilt[1]["call_id"] != "dup"
 
 
+@pytest.mark.asyncio
+async def test_blank_call_id_is_rejected_by_the_provider_without_the_wrapper(
+    blank_id_gateway: str,
+) -> None:
+    # Repro: the model answers with a tool call carrying no id, so the paired
+    # tool result goes back as a ``tool`` message with a blank ``tool_call_id``
+    # and the provider rejects the whole replayed history with a 400.
+    with pytest.raises(Exception, match="non-empty string tool_call_id"):
+        await _run_agent(blank_id_gateway, wrap=False)
+
+
+@pytest.mark.asyncio
+async def test_blank_call_id_is_filled_in_so_the_history_stays_valid(
+    blank_id_gateway: str,
+) -> None:
+    result = await _run_agent(blank_id_gateway, wrap=True)
+
+    assert result.final_output == "all done"
+    call_ids = _assistant_call_ids(_REQUESTS[-1])
+    assert len(call_ids) == 1
+    assert call_ids[0].startswith("call_")
+    assert _tool_results(_REQUESTS[-1]) == ["did 1"]
+
+
+def test_history_dedupe_fills_in_blank_ids_and_keeps_outputs_paired() -> None:
+    items = [
+        {"type": "function_call", "call_id": "", "name": "a", "arguments": "{}"},
+        {"type": "function_call", "call_id": "", "name": "b", "arguments": "{}"},
+        {"type": "function_call_output", "call_id": "", "output": "for-a"},
+        {"type": "function_call_output", "call_id": "", "output": "for-b"},
+    ]
+
+    rebuilt, changed = dedupe_history_call_ids(items)
+
+    assert changed
+    ids = [item["call_id"] for item in rebuilt]
+    assert all(call_id.startswith("call_") for call_id in ids)
+    assert ids[0] == ids[2]
+    assert ids[1] == ids[3]
+    assert ids[0] != ids[1]
+
+
+def test_history_dedupe_fills_in_a_missing_call_id_key() -> None:
+    items = [
+        {"type": "function_call", "name": "a", "arguments": "{}"},
+        {"type": "function_call_output", "output": "x"},
+    ]
+
+    rebuilt, changed = dedupe_history_call_ids(items)
+
+    assert changed
+    assert rebuilt[0]["call_id"] == rebuilt[1]["call_id"]
+    assert rebuilt[0]["call_id"].startswith("call_")
+
+
 def test_history_dedupe_leaves_unique_ids_alone() -> None:
     items = [
         {"type": "function_call", "call_id": "call_a", "name": "a", "arguments": "{}"},
@@ -247,3 +354,29 @@ def test_turn_rewriter_is_stable_across_repeated_sightings() -> None:
 
     assert first.call_id != "exec_command:0"
     assert second.call_id == first.call_id
+
+
+def test_turn_rewriter_fills_in_a_blank_id_stably() -> None:
+    rewriter = TurnCallIdRewriter([])
+    call = ResponseFunctionToolCall(
+        id="fc_1", call_id="", name="a", arguments="{}", type="function_call"
+    )
+
+    first = rewriter.rewrite_item(call)
+    second = rewriter.rewrite_item(call)
+
+    assert first.call_id.startswith("call_")
+    assert second.call_id == first.call_id
+    assert rewriter.rewrite_item(first).call_id == first.call_id
+
+
+def test_turn_rewriter_gives_parallel_blank_calls_distinct_ids() -> None:
+    rewriter = TurnCallIdRewriter([])
+    a = ResponseFunctionToolCall(
+        id="fc_1", call_id="", name="a", arguments="{}", type="function_call"
+    )
+    b = ResponseFunctionToolCall(
+        id="fc_2", call_id="", name="b", arguments="{}", type="function_call"
+    )
+
+    assert rewriter.rewrite_item(a).call_id != rewriter.rewrite_item(b).call_id

tests/test_tool_call_ids_providers.py

@@ -0,0 +1,379 @@
+"""Tool-call id repair across provider routes, models, and streaming modes.
+
+Every model Strix resolves goes through ``StrixProvider``, which picks the
+OpenAI SDK for ``openai/...`` and LiteLLM for every other prefix, then wraps the
+result in the turn guard that repairs tool-call ids. Each route parses a
+provider's tool calls on its own code path, so a blank or missing id — or a
+per-turn counter that repeats — has to be repaired no matter which route
+carried it, streamed or not.
+
+A local OpenAI-compatible gateway stands in for the provider. It hands out
+tool calls with whatever ids the scenario calls for and rejects a history the
+way strict providers do: any ``tool`` message with an empty ``tool_call_id``,
+or two assistant tool calls sharing one id.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from contextlib import contextmanager
+from dataclasses import dataclass
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from typing import TYPE_CHECKING, Any, ClassVar
+
+import litellm
+import pytest
+from agents import Agent, ModelSettings, Runner, function_tool
+from agents.run import RunConfig
+
+from strix.config import loader
+from strix.config import models as strix_models
+from strix.config.models import StrixProvider
+
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+
+_MISSING = object()
+
+
+@dataclass(frozen=True)
+class _Scenario:
+    """Tool-call ids the gateway hands out, one list per tool-calling turn."""
+
+    turns: tuple[tuple[Any, ...], ...]
+
+    @property
+    def calls(self) -> int:
+        return sum(len(turn) for turn in self.turns)
+
+    @property
+    def has_null_id(self) -> bool:
+        return any(
+            call_id is None or call_id is _MISSING for turn in self.turns for call_id in turn
+        )
+
+
+SCENARIOS = {
+    "empty-id": _Scenario(turns=(("",),)),
+    "null-id": _Scenario(turns=((None,),)),
+    "missing-id": _Scenario(turns=((_MISSING,),)),
+    "parallel-empty-ids": _Scenario(turns=(("", ""),)),
+    "empty-id-every-turn": _Scenario(turns=(("",), ("",), ("",))),
+    "recycled-counter": _Scenario(turns=(("exec_command:0",), ("exec_command:0",))),
+    "parallel-recycled-counter": _Scenario(
+        turns=(("exec_command:0", "exec_command:1"), ("exec_command:0", "exec_command:1"))
+    ),
+    "mixed-blank-and-recycled": _Scenario(
+        turns=(("exec_command:0", ""), ("exec_command:0", None), (_MISSING,))
+    ),
+    "valid-ids": _Scenario(turns=(("call_a",), ("call_b", "call_c"))),
+}
+
+# One model per provider family Strix recommends or documents, each on the
+# route ``StrixProvider`` gives it: the OpenAI SDK for ``openai/``, LiteLLM's
+# OpenAI-compatible adapters for the rest, and a generic OpenAI-compatible
+# endpoint through ``litellm/openai/``.
+MODELS = [
+    "openai/gpt-5.4",
+    "openrouter/z-ai/glm-5.3",
+    "openrouter/anthropic/claude-sonnet-4.6",
+    "openrouter/google/gemini-3-pro-preview",
+    "openrouter/qwen/qwen3-coder",
+    "zai/glm-5.3",
+    "zai/glm-5.3-flash",
+    "deepseek/deepseek-chat",
+    "moonshot/kimi-k2.5",
+    "xai/grok-4",
+    "mistral/mistral-large-latest",
+    "together_ai/Qwen/Qwen3-235B-A22B",
+    "fireworks_ai/accounts/fireworks/models/kimi-k2",
+    "dashscope/qwen3-max",
+    "deepinfra/Qwen/Qwen3-32B",
+    "nebius/Qwen/Qwen3-32B",
+    "hosted_vllm/Qwen/Qwen3-32B",
+    "litellm/openai/gw-model",
+]
+
+
+class _Gateway(BaseHTTPRequestHandler):
+    scenario: ClassVar[_Scenario]
+    requests: ClassVar[list[dict[str, Any]]]
+    lock: ClassVar[threading.Lock]
+
+    def log_message(self, *args: Any) -> None:
+        pass
+
+    def do_POST(self) -> None:  # noqa: N802
+        length = int(self.headers.get("Content-Length", 0))
+        body = json.loads(self.rfile.read(length) or b"{}")
+        messages = body.get("messages", [])
+        with self.lock:
+            self.requests.append(body)
+            turn = len(self.requests) - 1
+
+        error = _history_error(messages)
+        if error:
+            self._send_json(400, {"error": {"message": error, "code": 400}})
+            return
+
+        if turn < len(self.scenario.turns):
+            ids = self.scenario.turns[turn]
+            message = _tool_call_message(ids, first_n=turn * 10)
+            finish = "tool_calls"
+        else:
+            message = {"role": "assistant", "content": "all done"}
+            finish = "stop"
+
+        if body.get("stream"):
+            self._send_stream(message, finish)
+        else:
+            self._send_json(
+                200,
+                {
+                    "id": f"chatcmpl-{turn}",
+                    "object": "chat.completion",
+                    "created": 0,
+                    "model": body.get("model", "gw-model"),
+                    "choices": [{"index": 0, "finish_reason": finish, "message": message}],
+                    "usage": {"prompt_tokens": 5, "completion_tokens": 2, "total_tokens": 7},
+                },
+            )
+
+    def _send_json(self, status: int, payload: dict[str, Any]) -> None:
+        encoded = json.dumps(payload).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(encoded)))
+        self.end_headers()
+        self.wfile.write(encoded)
+
+    def _send_stream(self, message: dict[str, Any], finish: str) -> None:
+        self.send_response(200)
+        self.send_header("Content-Type", "text/event-stream")
+        self.end_headers()
+
+        def chunk(delta: dict[str, Any], finish_reason: str | None = None) -> None:
+            payload = {
+                "id": "chatcmpl-s",
+                "object": "chat.completion.chunk",
+                "created": 0,
+                "model": "gw-model",
+                "choices": [{"index": 0, "delta": delta, "finish_reason": finish_reason}],
+            }
+            self.wfile.write(f"data: {json.dumps(payload)}\n\n".encode())
+
+        chunk({"role": "assistant", "content": ""})
+        if message.get("content"):
+            chunk({"content": message["content"]})
+        for index, call in enumerate(message.get("tool_calls") or []):
+            head: dict[str, Any] = {
+                "index": index,
+                "type": "function",
+                "function": {"name": call["function"]["name"], "arguments": ""},
+            }
+            if "id" in call:
+                head["id"] = call["id"]
+            chunk({"tool_calls": [head]})
+            arguments = call["function"]["arguments"]
+            middle = len(arguments) // 2
+            for part in (arguments[:middle], arguments[middle:]):
+                chunk({"tool_calls": [{"index": index, "function": {"arguments": part}}]})
+        chunk({}, finish)
+        usage = {
+            "id": "chatcmpl-s",
+            "object": "chat.completion.chunk",
+            "created": 0,
+            "model": "gw-model",
+            "choices": [],
+            "usage": {"prompt_tokens": 5, "completion_tokens": 2, "total_tokens": 7},
+        }
+        self.wfile.write(f"data: {json.dumps(usage)}\n\n".encode())
+        self.wfile.write(b"data: [DONE]\n\n")
+        self.wfile.flush()
+
+
+def _tool_call_message(ids: tuple[Any, ...], *, first_n: int) -> dict[str, Any]:
+    calls = []
+    for offset, call_id in enumerate(ids):
+        call: dict[str, Any] = {
+            "type": "function",
+            "function": {"name": "do_thing", "arguments": json.dumps({"n": first_n + offset})},
+        }
+        if call_id is not _MISSING:
+            call["id"] = call_id
+        calls.append(call)
+    return {"role": "assistant", "content": None, "tool_calls": calls}
+
+
+def _history_error(messages: list[dict[str, Any]]) -> str | None:
+    seen: set[str] = set()
+    for index, message in enumerate(messages):
+        if message.get("role") == "tool":
+            call_id = message.get("tool_call_id")
+            if not isinstance(call_id, str) or not call_id:
+                return (
+                    f"messages[{index}]: tool messages must include a non-empty string tool_call_id"
+                )
+        for call in message.get("tool_calls") or []:
+            call_id = call.get("id")
+            if not isinstance(call_id, str) or not call_id:
+                return f"messages[{index}]: assistant tool_calls must include a non-empty id"
+            if call_id in seen:
+                return f"messages[{index}]: duplicate tool_call id {call_id!r}"
+            seen.add(call_id)
+    return None
+
+
+def _serve(scenario: _Scenario) -> tuple[HTTPServer, type[_Gateway]]:
+    handler = type(
+        "_ScenarioGateway",
+        (_Gateway,),
+        {"scenario": scenario, "requests": [], "lock": threading.Lock()},
+    )
+    server = HTTPServer(("127.0.0.1", 0), handler)
+    threading.Thread(target=server.serve_forever, daemon=True).start()
+    return server, handler
+
+
+@pytest.fixture(autouse=True)
+def _reset_settings(monkeypatch: pytest.MonkeyPatch) -> None:
+    for key in ("STRIX_LLM", "LLM_DISABLE_STREAMING", "LLM_MAX_TOOL_CALLS_PER_TURN"):
+        monkeypatch.delenv(key, raising=False)
+    monkeypatch.setattr(loader, "_cached", None)
+    monkeypatch.setattr(loader, "_override", None)
+    # As ``configure_sdk_model_defaults`` sets it, so routes like ``zai/`` that
+    # reject ``parallel_tool_calls`` still get a request out.
+    monkeypatch.setattr(litellm, "drop_params", True)
+
+
+@contextmanager
+def _gateway(scenario: _Scenario) -> Iterator[tuple[str, type[_Gateway]]]:
+    server, handler = _serve(scenario)
+    try:
+        yield f"http://127.0.0.1:{server.server_address[1]}/v1", handler
+    finally:
+        server.shutdown()
+        server.server_close()
+
+
+async def _run(
+    monkeypatch: pytest.MonkeyPatch, model: str, base_url: str, *, stream: bool, parallel: bool
+) -> tuple[Any, list[int]]:
+    monkeypatch.setenv("LLM_DISABLE_STREAMING", "false" if stream else "true")
+    monkeypatch.setattr(loader, "_cached", None)
+    # Binding the provider to the gateway sends every route there, the way a
+    # custom endpoint would, while each prefix keeps its own adapter.
+    provider = StrixProvider(api_key="tok", base_url=base_url)
+    ran: list[int] = []
+
+    @function_tool
+    def do_thing(n: int) -> str:
+        ran.append(n)
+        return f"did {n}"
+
+    agent = Agent(
+        name="t",
+        instructions="use the tool",
+        tools=[do_thing],
+        model=model,
+        model_settings=ModelSettings(parallel_tool_calls=parallel),
+    )
+    result = Runner.run_streamed(
+        agent, input="please", max_turns=10, run_config=RunConfig(model_provider=provider)
+    )
+    async for _ in result.stream_events():
+        pass
+    return result, ran
+
+
+def _final_history(handler: type[_Gateway]) -> list[dict[str, Any]]:
+    messages: list[dict[str, Any]] = handler.requests[-1]["messages"]
+    return messages
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stream", [True, False], ids=["streamed", "non-streamed"])
+@pytest.mark.parametrize("scenario_name", list(SCENARIOS))
+@pytest.mark.parametrize("model", MODELS)
+async def test_tool_call_ids_are_repaired_on_every_route(
+    request: pytest.FixtureRequest,
+    monkeypatch: pytest.MonkeyPatch,
+    model: str,
+    scenario_name: str,
+    *,
+    stream: bool,
+) -> None:
+    scenario = SCENARIOS[scenario_name]
+    if model.startswith("openai/") and not stream and scenario.has_null_id:
+        request.applymarker(
+            pytest.mark.xfail(
+                strict=True,
+                reason=(
+                    "the Agents SDK's Chat Completions converter rejects a null tool-call id "
+                    "in a non-streamed response before the turn guard sees it"
+                ),
+            )
+        )
+    with _gateway(scenario) as (base_url, handler):
+        result, ran = await _run(
+            monkeypatch,
+            model,
+            base_url,
+            stream=stream,
+            parallel=any(len(t) > 1 for t in scenario.turns),
+        )
+
+    assert result.final_output == "all done"
+    assert len(handler.requests) == len(scenario.turns) + 1
+    assert all(bool(body.get("stream")) is stream for body in handler.requests)
+
+    history = _final_history(handler)
+    call_ids = [call["id"] for m in history for call in m.get("tool_calls") or []]
+    assert len(call_ids) == scenario.calls
+    assert all(isinstance(call_id, str) and call_id for call_id in call_ids)
+    assert len(set(call_ids)) == len(call_ids)
+
+    outputs = {m["tool_call_id"]: m["content"] for m in history if m.get("role") == "tool"}
+    assert set(outputs) == set(call_ids)
+
+    originals = {
+        turn * 10 + offset: call_id
+        for turn, ids in enumerate(scenario.turns)
+        for offset, call_id in enumerate(ids)
+    }
+    assert sorted(ran) == sorted(originals)
+
+    # Each output still answers the call that produced it.
+    id_by_n = {
+        json.loads(call["function"]["arguments"])["n"]: call["id"]
+        for m in history
+        for call in m.get("tool_calls") or []
+    }
+    assert {id_by_n[n]: f"did {n}" for n in originals} == outputs
+
+    # A usable id is kept the first time it appears; only blanks and repeats change.
+    seen: set[str] = set()
+    for n, original in sorted(originals.items()):
+        if isinstance(original, str) and original and original not in seen:
+            assert id_by_n[n] == original
+            seen.add(original)
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("stream", [True, False], ids=["streamed", "non-streamed"])
+@pytest.mark.parametrize("model", MODELS)
+async def test_blank_call_id_is_rejected_on_every_route_without_the_guard(
+    monkeypatch: pytest.MonkeyPatch, model: str, *, stream: bool
+) -> None:
+    # Repro: with the turn guard removed, an empty id reaches the provider on
+    # every route, so the matrix above is exercising the repair and not a
+    # route that happens to fill ids in on its own.
+    monkeypatch.setattr(strix_models, "_TurnGuardModel", lambda model, **_: model)
+    with (
+        _gateway(SCENARIOS["empty-id"]) as (base_url, _handler),
+        pytest.raises(Exception, match="must include a non-empty"),
+    ):
+        await _run(monkeypatch, model, base_url, stream=stream, parallel=False)