feat(agents): add progressive tool disclosure

Dockerfile

@@ -595,12 +595,16 @@ COPY nemoclaw-blueprint/scripts/*.js /usr/local/lib/nemoclaw/preloads/
 COPY --from=runtime-preload-builder /opt/nemoclaw-root/dist/lib/messaging/channels/ /usr/local/lib/nemoclaw/preloads-compiled-channels/
 COPY scripts/codex-acp-wrapper.sh /usr/local/bin/nemoclaw-codex-acp
 COPY scripts/generate-openclaw-config.mts /scripts/generate-openclaw-config.mts
+COPY scripts/validate-openclaw-tool-search.mts /scripts/validate-openclaw-tool-search.mts
+COPY src/lib/tool-disclosure.ts /src/lib/tool-disclosure.ts
 COPY src/lib/messaging/ /src/lib/messaging/
 COPY nemoclaw-blueprint/openclaw-plugins/ /usr/local/share/nemoclaw/openclaw-plugins/
 RUN chmod 755 /usr/local/bin/nemoclaw-start /usr/local/bin/nemoclaw-codex-acp \
         /usr/local/lib/nemoclaw/sandbox-init.sh \
         /scripts/generate-openclaw-config.mts \
+        /scripts/validate-openclaw-tool-search.mts \
         /src/lib/messaging/applier/build/messaging-build-applier.mts \
+    && chmod 444 /src/lib/tool-disclosure.ts \
     && chmod -R a+rX /src/lib/messaging \
     && chown root:root /usr/local/bin/nemoclaw-gateway-control \
         /usr/local/lib/nemoclaw/gateway-supervisor.sh \
@@ -645,6 +649,7 @@ ARG NEMOCLAW_INFERENCE_API=openai-completions
 ARG NEMOCLAW_CONTEXT_WINDOW=131072
 ARG NEMOCLAW_MAX_TOKENS=4096
 ARG NEMOCLAW_REASONING=false
+ARG NEMOCLAW_TOOL_DISCLOSURE=progressive
 # Comma-separated list of input modalities accepted by the primary model
 # (e.g. "text" or "text,image" for vision-capable models). OpenClaw's
 # model schema currently accepts "text" and "image". See #2421.
@@ -714,6 +719,7 @@ ENV NEMOCLAW_MODEL=${NEMOCLAW_MODEL} \
     NEMOCLAW_CONTEXT_WINDOW=${NEMOCLAW_CONTEXT_WINDOW} \
     NEMOCLAW_MAX_TOKENS=${NEMOCLAW_MAX_TOKENS} \
     NEMOCLAW_REASONING=${NEMOCLAW_REASONING} \
+    NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE} \
     NEMOCLAW_INFERENCE_INPUTS=${NEMOCLAW_INFERENCE_INPUTS} \
     NEMOCLAW_AGENT_TIMEOUT=${NEMOCLAW_AGENT_TIMEOUT} \
     NEMOCLAW_AGENT_HEARTBEAT_EVERY=${NEMOCLAW_AGENT_HEARTBEAT_EVERY} \
@@ -762,6 +768,31 @@ USER sandbox
 # block until after build-time OpenClaw doctor/plugin commands complete.
 RUN NEMOCLAW_OPENCLAW_MANAGED_PROXY=0 node --experimental-strip-types /scripts/generate-openclaw-config.mts
 
+# Validate the patched OpenClaw tool-search contract against real generated
+# configs for both supported disclosure modes. This runs at image build time so
+# OpenClaw dist drift or a generator/schema mismatch fails the build closed.
+# hadolint ignore=DL3059
+RUN set -eu; \
+    validation_root="$(mktemp -d /tmp/nemoclaw-openclaw-tool-search.XXXXXX)"; \
+    trap 'rm -rf "$validation_root"' EXIT; \
+    for mode in progressive direct; do \
+        validation_home="$validation_root/$mode"; \
+        mkdir -p "$validation_home"; \
+        HOME="$validation_home" \
+            NEMOCLAW_MODEL=test-model \
+            NEMOCLAW_PRIMARY_MODEL_REF=inference/test-model \
+            NEMOCLAW_TOOL_DISCLOSURE="$mode" \
+            NEMOCLAW_OPENCLAW_MANAGED_PROXY=0 \
+            node --experimental-strip-types /scripts/generate-openclaw-config.mts; \
+        node --experimental-strip-types /scripts/validate-openclaw-tool-search.mts \
+            /usr/local/lib/node_modules/openclaw/dist \
+            "$validation_home/.openclaw/openclaw.json" \
+            "$mode" \
+            "$OPENCLAW_VERSION"; \
+    done; \
+    rm -rf "$validation_root"; \
+    trap - EXIT
+
 # Install non-messaging OpenClaw plugins that need to match the runtime.
 # hadolint ignore=DL3059,DL4006
 RUN set -eu; \

agents/hermes/Dockerfile

@@ -104,9 +104,11 @@ RUN chmod -R a+rX /opt/nemoclaw-hermes-plugin/
 COPY agents/hermes/generate-config.ts /opt/nemoclaw-hermes-config/generate-config.ts
 COPY agents/hermes/config/ /opt/nemoclaw-hermes-config/config/
 COPY agents/hermes/host/managed-tool-gateway-matrix.json /opt/nemoclaw-hermes-config/managed-tool-gateway-matrix.json
+COPY src/lib/tool-disclosure.ts /src/lib/tool-disclosure.ts
 COPY src/lib/messaging/ /src/lib/messaging/
 RUN find /opt/nemoclaw-hermes-config -type d -exec chmod 755 {} + \
     && find /opt/nemoclaw-hermes-config -type f -exec chmod 444 {} + \
+    && chmod 444 /src/lib/tool-disclosure.ts \
     && chmod -R a+rX /src/lib/messaging
 
 # Copy blueprint (shared infrastructure)
@@ -219,6 +221,7 @@ ARG NEMOCLAW_PROVIDER_KEY=custom
 ARG NEMOCLAW_UPSTREAM_PROVIDER=custom
 ARG NEMOCLAW_INFERENCE_BASE_URL=https://inference.local/v1
 ARG NEMOCLAW_INFERENCE_API=openai-completions
+ARG NEMOCLAW_TOOL_DISCLOSURE=progressive
 # CHAT_UI_URL is a legacy name shared with the OpenClaw build arg. For
 # Hermes this URL points at the browser dashboard. The OpenAI-compatible
 # API remains exposed separately on port 8642.
@@ -237,6 +240,7 @@ ENV NEMOCLAW_MODEL=${NEMOCLAW_MODEL} \
     NEMOCLAW_UPSTREAM_PROVIDER=${NEMOCLAW_UPSTREAM_PROVIDER} \
     NEMOCLAW_INFERENCE_BASE_URL=${NEMOCLAW_INFERENCE_BASE_URL} \
     NEMOCLAW_INFERENCE_API=${NEMOCLAW_INFERENCE_API} \
+    NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE} \
     CHAT_UI_URL=${CHAT_UI_URL} \
     NEMOCLAW_MESSAGING_PLAN_B64=${NEMOCLAW_MESSAGING_PLAN_B64} \
     NEMOCLAW_WEB_SEARCH_ENABLED=${NEMOCLAW_WEB_SEARCH_ENABLED} \

agents/hermes/config/build-env.ts

@@ -4,6 +4,7 @@
 import { Buffer } from "node:buffer";
 
 import { normalizeProviderPlaceholderForEnvKey } from "../../../src/lib/messaging/provider-placeholders.ts";
+import { readToolDisclosureEnv } from "../../../src/lib/tool-disclosure.ts";
 
 export type HermesWebSearchProvider = "tavily";
 
@@ -13,6 +14,7 @@ export type HermesBuildSettings = {
   providerKey: string;
   upstreamProvider: string;
   inferenceApi: string;
+  toolDisclosure: "progressive" | "direct";
   webSearchProvider: HermesWebSearchProvider | null;
   messagingCredentialPlaceholders: Array<{
     envKey: string;
@@ -34,6 +36,7 @@ export function readHermesBuildSettings(env: NodeJS.ProcessEnv): HermesBuildSett
     providerKey: env.NEMOCLAW_PROVIDER_KEY || "custom",
     upstreamProvider: env.NEMOCLAW_UPSTREAM_PROVIDER || env.NEMOCLAW_PROVIDER_KEY || "custom",
     inferenceApi: env.NEMOCLAW_INFERENCE_API || "",
+    toolDisclosure: readToolDisclosureEnv(env),
     webSearchProvider: readWebSearchProvider(env),
     messagingCredentialPlaceholders: readMessagingCredentialPlaceholders(env),
     managedToolGateways: {

agents/hermes/config/hermes-config.ts

@@ -102,6 +102,17 @@ export function buildHermesConfig(settings: HermesBuildSettings): Record<string,
       max_turns: 60,
       reasoning_effort: "medium",
     },
+    tools: {
+      tool_search: {
+        // Deliberately defer every MCP and non-core plugin tool, even for a
+        // small catalog. Hermes keeps its built-in core tools directly visible.
+        // Keep Hermes' native snake_case keys and 5/20 limits distinct from
+        // OpenClaw's camelCase Tool Search contract and 8-result default.
+        enabled: settings.toolDisclosure === "direct" ? "off" : "on",
+        search_default_limit: 5,
+        max_search_limit: 20,
+      },
+    },
     memory: {
       memory_enabled: true,
       user_profile_enabled: true,

agents/langchain-deepagents-code/Dockerfile

@@ -23,14 +23,20 @@ RUN set -eu; \
 COPY agents/langchain-deepagents-code/generate-config.ts /opt/nemoclaw-deepagents-code/generate-config.ts
 COPY agents/langchain-deepagents-code/managed-dcode-runtime.py /opt/nemoclaw-deepagents-code/managed-dcode-runtime.py
 COPY agents/langchain-deepagents-code/patch-managed-deepagents-code.py /opt/nemoclaw-deepagents-code/patch-managed-deepagents-code.py
+COPY agents/langchain-deepagents-code/progressive_tool_disclosure.py /opt/nemoclaw-deepagents-code/progressive_tool_disclosure.py
+COPY agents/langchain-deepagents-code/validate-progressive-tool-disclosure.py /opt/nemoclaw-deepagents-code/validate-progressive-tool-disclosure.py
 COPY agents/langchain-deepagents-code/dcode-wrapper.sh /usr/local/lib/nemoclaw/dcode-wrapper.sh
 COPY agents/langchain-deepagents-code/dcode-launcher.sh /usr/local/lib/nemoclaw/dcode-launcher.sh
 COPY agents/langchain-deepagents-code/start.sh /usr/local/bin/nemoclaw-start
 COPY nemoclaw-blueprint/ /opt/nemoclaw-blueprint/
-RUN chmod 444 /opt/nemoclaw-deepagents-code/generate-config.ts /opt/nemoclaw-deepagents-code/managed-dcode-runtime.py /opt/nemoclaw-deepagents-code/patch-managed-deepagents-code.py \
+RUN chmod 444 /opt/nemoclaw-deepagents-code/generate-config.ts /opt/nemoclaw-deepagents-code/managed-dcode-runtime.py /opt/nemoclaw-deepagents-code/patch-managed-deepagents-code.py /opt/nemoclaw-deepagents-code/progressive_tool_disclosure.py /opt/nemoclaw-deepagents-code/validate-progressive-tool-disclosure.py \
     && chmod 755 /usr/local/bin/nemoclaw-start /usr/local/lib/nemoclaw/dcode-wrapper.sh /usr/local/lib/nemoclaw/dcode-launcher.sh \
     && chmod -R a+rX /opt/nemoclaw-blueprint \
     && python3 /opt/nemoclaw-deepagents-code/patch-managed-deepagents-code.py \
+    && install -d -m 0700 /tmp/nemoclaw-progressive-validation \
+    && TMPDIR=/tmp/nemoclaw-progressive-validation python3 /opt/nemoclaw-deepagents-code/validate-progressive-tool-disclosure.py \
+    && rm -rf /tmp/nemoclaw-progressive-validation \
+    && rm -f /opt/nemoclaw-deepagents-code/validate-progressive-tool-disclosure.py \
     && rm -f /usr/local/bin/dcode /usr/local/bin/deepagents-code /opt/venv/bin/dcode /opt/venv/bin/deepagents-code \
     && install -m 0755 /usr/local/lib/nemoclaw/dcode-launcher.sh /usr/local/bin/dcode \
     && install -m 0755 /usr/local/lib/nemoclaw/dcode-launcher.sh /usr/local/bin/dcode.real \
@@ -41,11 +47,17 @@ ARG NEMOCLAW_PROVIDER_KEY=inference
 ARG NEMOCLAW_UPSTREAM_PROVIDER=nvidia
 ARG NEMOCLAW_INFERENCE_BASE_URL=https://inference.local/v1
 ARG NEMOCLAW_INFERENCE_API=openai-completions
+ARG NEMOCLAW_TOOL_DISCLOSURE=progressive
 ARG NEMOCLAW_BUILD_ID=default
 ARG NEMOCLAW_DARWIN_VM_COMPAT=0
 ARG NEMOCLAW_PROXY_HOST=10.200.0.1
 ARG NEMOCLAW_PROXY_PORT=3128
 
+RUN case "$NEMOCLAW_TOOL_DISCLOSURE" in \
+        progressive|direct) ;; \
+        *) echo "ERROR: NEMOCLAW_TOOL_DISCLOSURE must be progressive or direct" >&2; exit 1 ;; \
+    esac
+
 # The launcher and startup script read these root-owned files instead of
 # trusting process-level environment overrides for inference routing. Invoking
 # each launcher validates the build args before the image can complete.
@@ -67,6 +79,7 @@ ENV HOME=/sandbox \
     NEMOCLAW_UPSTREAM_PROVIDER=${NEMOCLAW_UPSTREAM_PROVIDER} \
     NEMOCLAW_INFERENCE_BASE_URL=${NEMOCLAW_INFERENCE_BASE_URL} \
     NEMOCLAW_INFERENCE_API=${NEMOCLAW_INFERENCE_API} \
+    NEMOCLAW_TOOL_DISCLOSURE=${NEMOCLAW_TOOL_DISCLOSURE} \
     NEMOCLAW_BUILD_ID=${NEMOCLAW_BUILD_ID} \
     DEEPAGENTS_CODE_NO_UPDATE_CHECK=1 \
     LANGGRAPH_NO_VERSION_CHECK=true \

agents/langchain-deepagents-code/patch-managed-deepagents-code.py

@@ -24,6 +24,8 @@
 
 EXPECTED_DCODE_VERSION = "0.1.30"
 PATCH_MARKER = "NemoClaw-managed Deep Agents Code hardening v2."
+TOOL_DISCLOSURE_PATCH_MARKER = "NemoClaw-managed progressive tool disclosure."
+MIDDLEWARE_MODULE = "progressive_tool_disclosure.py"
 MANAGED_RUNTIME_SOURCE_PATH = Path(__file__).with_name("managed-dcode-runtime.py")
 
 MAIN_MARKER = "    args = parser.parse_args()\n"
@@ -396,20 +398,90 @@ def _nemoclaw_get_class_path(self, provider_name: str):
 ModelConfig.get_class_path = _nemoclaw_get_class_path
 '''
 
+# Source-of-truth boundary: pinned upstream deepagents-code==0.1.30 has no
+# supported managed progressive-disclosure middleware hook in its agent factory
+# API, and this repository cannot change that third-party package source.
+# Patcher/unit guards plus validate-progressive-tool-disclosure.py cover this
+# fail-closed integration. Remove it once upstream provides a supported hook
+# preserving managed MCP, credentials, approvals, executor, sandbox, and private
+# checkpoint-state boundaries.
 AGENT_PATCH = r'''
 
 # NemoClaw-managed Deep Agents Code hardening v2.
+# NemoClaw-managed progressive tool disclosure.
+from contextvars import ContextVar as _NemoClawContextVar
+
 _nemoclaw_original_create_cli_agent = create_cli_agent
+_nemoclaw_original_create_deep_agent = globals().get("create_deep_agent")
+_nemoclaw_progressive_disclosure_active = _NemoClawContextVar(
+    "nemoclaw_progressive_disclosure_active", default=False
+)
+
+
+def _nemoclaw_create_deep_agent(*args, **kwargs):
+    """Install distinct disclosure middleware in the main and local subagent graphs."""
+    if _nemoclaw_original_create_deep_agent is None:
+        raise RuntimeError("Deep Agents Code create_deep_agent boundary is unavailable")
+    if not _nemoclaw_progressive_disclosure_active.get():
+        return _nemoclaw_original_create_deep_agent(*args, **kwargs)
+    from deepagents_code.progressive_tool_disclosure import (
+        ProgressiveToolDisclosureMiddleware,
+    )
+
+    middleware = list(kwargs.get("middleware") or ())
+    middleware.append(ProgressiveToolDisclosureMiddleware())
+    kwargs["middleware"] = middleware
+
+    subagents = kwargs.get("subagents")
+    if subagents:
+        patched_subagents = []
+        for subagent in subagents:
+            if isinstance(subagent, dict):
+                subagent_middleware = list(subagent.get("middleware") or ())
+                subagent_middleware.append(ProgressiveToolDisclosureMiddleware())
+                subagent = {**subagent, "middleware": subagent_middleware}
+            patched_subagents.append(subagent)
+        kwargs["subagents"] = patched_subagents
+
+    return _nemoclaw_original_create_deep_agent(*args, **kwargs)
+
+
+if _nemoclaw_original_create_deep_agent is not None:
+    create_deep_agent = _nemoclaw_create_deep_agent
 
 
 def create_cli_agent(model, assistant_id, *args, **kwargs):
-    """Keep secondary model and remote-agent paths on the managed graph."""
+    """Keep managed graph posture and progressively disclose loaded MCP tools."""
     kwargs["rubric_model"] = None
     kwargs["async_subagents"] = None
-    return _nemoclaw_original_create_cli_agent(
-        model, assistant_id, *args, **kwargs
+    from deepagents_code.progressive_tool_disclosure import (
+        assert_unique_callable_tool_names,
     )
 
+    assert_unique_callable_tool_names(
+        kwargs.get("tools"), kwargs.get("mcp_server_info")
+    )
+    has_loaded_mcp_tools = any(
+        getattr(info, "tools", ()) for info in kwargs.get("mcp_server_info") or ()
+    )
+    if has_loaded_mcp_tools:
+        from deepagents_code.progressive_tool_disclosure import (
+            progressive_tool_disclosure_enabled,
+        )
+
+        progressive_active = progressive_tool_disclosure_enabled()
+    else:
+        progressive_active = False
+    if progressive_active and _nemoclaw_original_create_deep_agent is None:
+        raise RuntimeError("Deep Agents Code create_deep_agent boundary is unavailable")
+    token = _nemoclaw_progressive_disclosure_active.set(progressive_active)
+    try:
+        return _nemoclaw_original_create_cli_agent(
+            model, assistant_id, *args, **kwargs
+        )
+    finally:
+        _nemoclaw_progressive_disclosure_active.reset(token)
+
 
 def _resolve_ptc_option(*args, **kwargs):
     """Disable interpreter programmatic tool calling at the final build boundary."""
@@ -891,16 +963,45 @@ def main() -> None:
     }
     texts = {name: path.read_text(encoding="utf-8") for name, path in paths.items()}
 
+    module_source_path = Path(__file__).with_name(MIDDLEWARE_MODULE)
+    module_destination_path = root / MIDDLEWARE_MODULE
+    if not module_source_path.is_file():
+        raise RuntimeError(
+            f"NemoClaw middleware source not found at {module_source_path}"
+        )
+    module_source = module_source_path.read_text(encoding="utf-8")
+    compile(module_source, str(module_destination_path), "exec")
+    if module_destination_path.exists() or module_destination_path.is_symlink():
+        if (
+            not module_destination_path.is_file()
+            or module_destination_path.is_symlink()
+            or module_destination_path.read_text(encoding="utf-8") != module_source
+        ):
+            raise RuntimeError(
+                f"Refusing to overwrite unexpected middleware at {module_destination_path}"
+            )
+
     marker_states = {PATCH_MARKER in text for text in texts.values()}
     helper_path = root / "_nemoclaw_managed.py"
     if marker_states == {True}:
         if not helper_path.is_file() or PATCH_MARKER not in helper_path.read_text(
             encoding="utf-8"
         ):
             raise RuntimeError("Managed package patch is partial: helper is missing")
+        if not module_destination_path.is_file():
+            raise RuntimeError("Managed package patch is partial: middleware is missing")
+        if texts["agent"].count(AGENT_PATCH.lstrip()) != 1:
+            raise RuntimeError(
+                f"Managed package progressive-disclosure patch is incomplete in {paths['agent']}"
+            )
         return
     if marker_states != {False} or helper_path.exists():
         raise RuntimeError("Managed package patch is partial; refusing mixed source state")
+    if TOOL_DISCLOSURE_PATCH_MARKER in texts["agent"]:
+        raise RuntimeError(
+            "Managed package progressive-disclosure patch is partial; "
+            "refusing mixed source state"
+        )
 
     _require_functions(paths["main"], texts["main"], {"parse_args"})
     _require_methods(
@@ -1124,6 +1225,8 @@ def main() -> None:
     for name, text in transformed.items():
         paths[name].write_text(text, encoding="utf-8")
     helper_path.write_text(managed_runtime_source, encoding="utf-8")
+    if not module_destination_path.exists():
+        module_destination_path.write_text(module_source, encoding="utf-8")
 
 
 if __name__ == "__main__":