fix(tool-search): reliably hide deferred MCP schemas by removing the ContextVar (closures + graph state) (#3342)

* feat(tool-search): add hash-scoped promoted state to ThreadState

* feat(tool-search): add immutable DeferredToolCatalog with stable hash

* feat(tool-search): add build_deferred_tool_setup + Command-writing tool_search

* refactor(tool-search): replace deferred-tool ContextVar with closures + graph state (#3272)

Build the deferred catalog + tool_search tool per agent from the policy-filtered
tool list (after skill allowed-tools), pass deferred_names + catalog_hash
explicitly to DeferredToolFilterMiddleware and the prompt, and record promotions
in ThreadState.promoted (scoped by catalog_hash) via a Command-returning
tool_search. Removes DeferredToolRegistry and the _registry_var ContextVar so
deferral no longer depends on build/execute sharing an async context. MCP tools
are tagged with metadata[deerflow_mcp]; client.py assembles deferral the same way.

Catalog is built AFTER tool-policy filtering (no policy-excluded tool can leak via
tool_search) and assembly is fail-closed. Migrate tests off the deleted registry
APIs; delete the obsolete ContextVar-based #2884 regression (re-covered by
state-based tests in a follow-up).

* test(tool-search): lock tool_search promotion into next model turn via graph state

* test(tool-search): cross-context, policy-leak, fail-closed, #2884 isolation regressions

* test(tool-search): align real-LLM e2e with closure-based deferred setup

* docs: update DeferredToolFilterMiddleware description for closure+state design

* style(tests): drop unused import in test_deferred_setup (ruff)

* test(tool-search): harden merge_promoted + replace tautological catalog test

From independent code review:
- merge_promoted: use existing.get("catalog_hash") so a forward-incompatible
  or externally-injected persisted promoted dict triggers a replace instead of
  a KeyError crash; add regression test for the malformed-existing case.
- test_deferred_catalog: replace the `== [] or True` tautology (a test that
  could never fail) with a deterministic invalid-regex->literal-fallback check
  (positive match on calc + negative empty match).
- DeferredToolCatalog: comment why frozen-without-slots is required for the
  cached_property hash/names fields (adding slots=True would break them).

* fix(tool-search): read tool_search.enabled from self._app_config in client

DeerFlowClient._ensure_agent called get_app_config() directly to read
tool_search.enabled, but the client already resolves and stores its config as
self._app_config at construction (and uses it everywhere else). The bare call
re-resolves config from disk at agent-build time, which raises FileNotFoundError
in environments without a config.yaml (CI) — test_client.py's fixture only
patches get_app_config during __init__, so the later call hit the real loader.
Use self._app_config, matching the rest of the client.

* test(tool-search): lock tool_search post-policy append ordering

tool_search is appended after skill-allowlist filtering, so the allowlist
can no longer deny it by name. Lock the intended contract: it only appears
when allowed MCP tools survive the filter, and its catalog (derived from the
already policy-filtered list) can never expose a denied tool. Addresses the
ordering observation from the Copilot review on #3342.

backend/tests/test_deferred_tool_promotion_real_llm.py

@@ -82,15 +82,6 @@ def fake_translator(text: str, target_lang: str) -> str:
 # ---------------------------------------------------------------------------
 
 
-@pytest.fixture(autouse=True)
-def _reset_registry_between_tests():
-    from deerflow.tools.builtins.tool_search import reset_deferred_registry
-
-    reset_deferred_registry()
-    yield
-    reset_deferred_registry()
-
-
 def _patch_mcp_pipeline(monkeypatch: pytest.MonkeyPatch, mcp_tools: list) -> None:
     from deerflow.config.extensions_config import ExtensionsConfig, McpServerConfig
 
@@ -145,6 +136,7 @@ async def test_real_llm_promotes_then_invokes_with_subagent_reentry(monkeypatch:
     from langchain_openai import ChatOpenAI
 
     from deerflow.agents.middlewares.deferred_tool_filter_middleware import DeferredToolFilterMiddleware
+    from deerflow.tools.builtins.tool_search import build_deferred_tool_setup
     from deerflow.tools.tools import get_available_tools
 
     _patch_mcp_pipeline(monkeypatch, [fake_calculator, fake_translator])
@@ -158,18 +150,17 @@ async def test_real_llm_promotes_then_invokes_with_subagent_reentry(monkeypatch:
         Use this whenever the user asks you to delegate work — pass a short
         description as ``prompt``.
         """
-        # ``task_tool`` does this internally. Whether the registry-reset that
-        # used to happen here actually leaks back to the parent task depends
-        # on asyncio's implicit context-copying semantics (gather creates
-        # child tasks with copied contexts, so reset_deferred_registry is
-        # task-local) — but the fix in this PR is what GUARANTEES the
-        # promotion sticks regardless of which integration path triggers a
-        # re-entrant ``get_available_tools`` call.
+        # ``task_tool`` does this internally. With the closure + graph-state
+        # design there is no shared registry/ContextVar, so a re-entrant
+        # ``get_available_tools`` call here cannot affect the lead agent's
+        # deferred middleware or its promotion state.
         get_available_tools(subagent_enabled=False)
         _calls.append(f"fake_subagent_trigger:{prompt}")
         return "subagent completed"
 
-    tools = get_available_tools() + [fake_subagent_trigger]
+    raw_tools = get_available_tools() + [fake_subagent_trigger]
+    setup = build_deferred_tool_setup(raw_tools, enabled=True)
+    tools = [*raw_tools, setup.tool_search_tool] if setup.tool_search_tool else raw_tools
 
     model = ChatOpenAI(
         model=os.environ.get("ONEAPI_MODEL", "claude-sonnet-4-6"),
@@ -195,7 +186,7 @@ async def test_real_llm_promotes_then_invokes_with_subagent_reentry(monkeypatch:
     graph = create_agent(
         model=model,
         tools=tools,
-        middleware=[DeferredToolFilterMiddleware()],
+        middleware=[DeferredToolFilterMiddleware(setup.deferred_names, setup.catalog_hash)],
         system_prompt=system_prompt,
     )