feat(agents): add progressive tool disclosure

[ericksoa]

Summary

Adds a shared tool-disclosure mode across Deep Agents Code, Hermes, and OpenClaw. New sandboxes default to progressive; --tool-disclosure direct or NEMOCLAW_TOOL_DISCLOSURE=direct restores the prior fully visible catalog. The mode persists through resume and transactional rebuilds.

The design follows LangChain progressive disclosure, Hermes Tool Search, and the pinned OpenClaw v2026.5.27 Tool Search contract. This is the v0.0.74 bundle.

Exact head e4214144c11dd47b9d3185f19c1c73ec4e690552 includes main at 6f5ccbcbaa87367f7b521318fbc940467045b601.

Related Issue

#5876 is merged. This PR has no remaining stacked dependency and preserves its managed-MCP ownership contract.

Changes

• Add the shared --tool-disclosure progressive|direct onboarding and rebuild option, with NEMOCLAW_TOOL_DISCLOSURE as the environment equivalent. CLI input takes precedence and fresh sandboxes default to progressive.
• Persist the selected mode in session and registry state. Resume, recreation, and MCP-bearing rebuilds preserve or transactionally change it in either direction.
• Add bounded search_tools middleware to Deep Agents Code when at least one MCP tool loads successfully. Core tools remain visible, discovery state survives checkpointing, and only model requests are filtered; the complete executor registry and existing authorization controls remain intact.
• Enable Hermes native Tool Search with opinionated 5/20 result limits and direct core tools.
• Enable OpenClaw native structured mode: "tools" discovery with 8/20 limits while retaining model-specific compatibility safeguards.
• Patch and validate the exact pinned deepagents-code==0.1.30 runtime with fail-closed, idempotent anchors and separate middleware instances for the main agent and local subagents.
• Add build-time/runtime validators, lifecycle and overflow coverage, transactional custom-image handling, and user-facing documentation for progressive/direct behavior.

Managed MCP boundary

This PR does not change MCP configuration, credential placeholders, bridge ownership, policy generation, MCP CLI behavior, or registry schemas from #5876.

Managed OpenClaw MCP remains registered in mcporter's home registry. Pinned OpenClaw Tool Search reads native bundle and mcp.servers catalogs, and NemoClaw does not currently synchronize those ownership stores. The OpenClaw runtime validator therefore proves native search, describe, and call behavior for eligible hidden catalog tools, while the existing live MCP scenario separately proves mcporter execution, credential rewriting and rotation, restart/rebuild behavior, policy enforcement, DNS-rebinding protection, and secret boundaries. A fixture-only projection between those stores would not represent shipped behavior.

Apurv security review resolution

1. Callable namespace: Deep Agents Code rejects every duplicate resolved callable name and every non-managed owner of a reserved core name before the original factory in progressive and direct modes. Coverage includes regular/regular, regular/MCP, cross-MCP-server, direct-mode, and schema/executor mismatch cases.
2. Build-context seal: fingerprints require a real directory root and encode portable mode bits, nanosecond modification times, link counts, and deterministic hardlink topology. Pre-delete and final one-shot tests cover hardlink, timestamp, permission, and root-symlink mutations.
3. Dockerfile patch boundary: patching anchors and revalidates the staging parent, rejects multi-link files, writes a fresh private same-directory file, and atomically replaces the staged Dockerfile without truncating an attacker-selectable inode.
4. Chunk-safe diagnostics: raw cloudflared child output is not emitted in failures. Only bounded per-stream carry is retained for origin discovery, with split-event credential regressions proving fragments and reconstructed secrets remain absent.

CodeRabbit and CodeQL resolution

• Every CodeRabbit finding is implemented or explicitly dispositioned with repository evidence, including URL-token punctuation, the intentional private hosted model identifier, and the final Darwin fixture fail-fast nit. GraphQL reports zero unresolved review threads; exact-head CodeRabbit status is green.
• CodeQL alert #1210 is dismissed as a false positive. The flagged sink opens an existing directory read-only with O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK; it does not use O_CREAT. The real replacement file remains UUID-named, O_CREAT | O_EXCL | O_NOFOLLOW, mode 0600, descriptor/path identity checked, single-link validated, fsynced, and atomically renamed. Exact-head CodeQL is green with no open branch alerts.

Validation

• Local focused matrix: 19 files / 327 tests passed; one true Linux-only memfd/O_TMPFILE restart case was skipped on macOS.
• Exact pinned Deep Agents Code/LangChain patch and runtime validator passed: progressive-disclosure-runtime-ok.
• Both TypeScript typechecks, build, repository checks, source-shape/test-size guards, Biome, Ruff/Python compilation, secret scanning, push checks, and git diff --check passed.
• Final-head standard validation is green: PR CI, growth guardrails, WSL, macOS, security, CodeQL, review advisors, and the E2E advisor. The original exact-head check set and subsequent metadata checks are all green, with only the two expected skips.
• The exact-head typed OpenClaw and Deep Agents targets passed.
• The exact-head production-image workflow passed both requested image builds and all four downstream image E2E checks.
• The exact-head advisor-selected live union passed all 19 concrete jobs on attempt 2. The only rerun was Hermes security posture after a transient deliberate recovery-probe failure; the independent exact-head security confirmation also passed both Hermes and OpenClaw legs.
• The GPT review advisor's remaining OpenClaw MCP model-loop warning is explicitly dispositioned by the managed-MCP ownership boundary above: the native OpenClaw catalog and mcporter registry are separate shipped stores, and a test-only projection would claim behavior the production bridge does not provide.

Remaining

• Obtain Apurv's exact-head re-review to clear the formal CHANGES_REQUESTED state and complete sensitive-path approval.
• Rebuild affected existing sandboxes after this change ships; newly created sandboxes default to progressive disclosure.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Apurv exact-head re-review pending after all four requested fixes.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue: no waiver requested; exact-head security retry is green.

Verification

• PR description includes the DCO sign-off declaration and every feature commit appears as Verified in GitHub
• Git hooks passed during commit and push, or npx prek run --from-ref main --to-ref HEAD passes — all applicable hooks passed; the known hanging local unsharded test-cli coverage hook was skipped and exact-head sharded Linux CI is authoritative.
• Targeted tests pass for changed behavior
• Full npm test passes (broad runtime changes only)
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only; current build has two pre-existing warnings)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only; no new doc pages)

---

Signed-off-by: Aaron Erickson aerickson@nvidia.com

[ericksoa]

Exact head 6cf1aa4 addresses CodeQL alert #1210. The flagged call opens an existing staging directory read-only with O_DIRECTORY, O_NOFOLLOW, and O_NONBLOCK; it does not create a temporary file. The actual atomic-replacement file remains UUID-named, O_CREAT|O_EXCL|O_NOFOLLOW, mode 0600, and descriptor/path identity plus single-link validated. I added the repository-standard narrowly scoped CodeQL annotation at the false-positive sink with this rationale. Biome, CLI typecheck, 46 focused Dockerfile security/patch tests, commit hooks, and push checks pass. @coderabbitai review

[coderabbitai]

@ericksoa Understood — the rationale for the CodeQL suppression at that sink (existing-directory read-only open vs. the actual atomic-replacement file creation with UUID naming, O_CREAT|O_EXCL|O_NOFOLLOW, mode 0600, and identity validation) makes sense. Triggering a fresh review on exact head 6cf1aa4c.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

🧹 Nitpick comments (1)

test/langchain-deepagents-code-direct-module-patch.test.ts (1)

12-40: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value

Silent no-op if the injection marker text doesn't match.

helper.replace("import fcntl\n", ...) silently returns the original string unchanged if that exact literal isn't found (e.g., generated helper reformats the import line). On Darwin this would leave fcntl.F_SEAL_* undefined, producing a confusing downstream AttributeError at import time rather than a clear diagnostic pointing at the patch itself.

♻️ Proposed fix to fail fast with a clear message

 function addDarwinFcntlSealConstants(helper: string): string {
-  return process.platform !== "darwin" || helper.includes(DARWIN_FCNTL_FIXTURE_MARKER)
-    ? helper
-    : helper.replace(
-        "import fcntl\n",
-        `import fcntl
+  if (process.platform !== "darwin" || helper.includes(DARWIN_FCNTL_FIXTURE_MARKER)) {
+    return helper;
+  }
+  const patched = helper.replace(
+    "import fcntl\n",
+    `import fcntl
 
 ${DARWIN_FCNTL_FIXTURE_MARKER}
 for _name, _value in (
     ("F_ADD_SEALS", 1033),
     ("F_GET_SEALS", 1034),
     ("F_SEAL_SEAL", 0x0001),
     ("F_SEAL_SHRINK", 0x0002),
     ("F_SEAL_GROW", 0x0004),
     ("F_SEAL_WRITE", 0x0008),
 ):
     if not hasattr(fcntl, _name):
         setattr(fcntl, _name, _value)
 `,
-      );
+  );
+  if (patched === helper) {
+    throw new Error("Darwin fcntl seal shim injection point not found in helper module");
+  }
+  return patched;
 }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@test/langchain-deepagents-code-direct-module-patch.test.ts` around lines 12 -
40, The addDarwinFcntlSealConstants helper can silently do nothing when the
exact import marker is missing, which leaves the Darwin seal constants unset.
Update this function to fail fast with a clear error if the expected injection
point is not found in the helper text, instead of returning the original string
unchanged. Use the existing addDarwinFcntlSealConstants and
DARWIN_FCNTL_FIXTURE_MARKER symbols to locate the logic, and make the failure
explicit so the patch problem is reported immediately.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@test/langchain-deepagents-code-direct-module-patch.test.ts`:
- Around line 12-40: The addDarwinFcntlSealConstants helper can silently do
nothing when the exact import marker is missing, which leaves the Darwin seal
constants unset. Update this function to fail fast with a clear error if the
expected injection point is not found in the helper text, instead of returning
the original string unchanged. Use the existing addDarwinFcntlSealConstants and
DARWIN_FCNTL_FIXTURE_MARKER symbols to locate the logic, and make the failure
explicit so the patch problem is reported immediately.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: fcfbc3e8-3919-4bad-8c87-65d4ec749df8

📥 Commits

Reviewing files that changed from the base of the PR and between f452c51 and 6cf1aa4.

📒 Files selected for processing (24)

• agents/langchain-deepagents-code/Dockerfile
• agents/langchain-deepagents-code/patch-managed-deepagents-code.py
• docs/reference/commands-nemohermes.mdx
• docs/reference/commands.mdx
• src/lib/actions/sandbox/rebuild-dcode-mutation-edge.test.ts
• src/lib/actions/sandbox/rebuild-dcode-orchestrator.test.ts
• src/lib/actions/sandbox/rebuild-dcode-orchestrator.ts
• src/lib/actions/sandbox/rebuild-dcode-pre-delete-drift.test.ts
• src/lib/actions/sandbox/rebuild-dcode-preflight.ts
• src/lib/actions/sandbox/rebuild-durable-config.test.ts
• src/lib/actions/sandbox/rebuild-durable-config.ts
• src/lib/actions/sandbox/rebuild-managed-image-preflight.ts
• src/lib/actions/sandbox/rebuild-managed-image-preparation.test.ts
• src/lib/actions/sandbox/rebuild-managed-image-verification.test.ts
• src/lib/actions/sandbox/rebuild-pipeline.ts
• src/lib/actions/sandbox/rebuild-preflight-phase.ts
• src/lib/onboard/dockerfile-tool-disclosure-contract.ts
• src/lib/security/redact.test.ts
• src/lib/security/redact.ts
• test/e2e/live/mcp-bridge.test.ts
• test/helpers/rebuild-managed-image-preflight-harness.ts
• test/langchain-deepagents-code-direct-module-patch.test.ts
• test/langchain-deepagents-code-image.test.ts
• test/langchain-deepagents-code-progressive-tool-disclosure.test.ts

🚧 Files skipped from review as they are similar to previous changes (14)

• src/lib/security/redact.test.ts
• src/lib/actions/sandbox/rebuild-dcode-orchestrator.test.ts
• src/lib/actions/sandbox/rebuild-dcode-orchestrator.ts
• src/lib/actions/sandbox/rebuild-durable-config.test.ts
• src/lib/actions/sandbox/rebuild-preflight-phase.ts
• agents/langchain-deepagents-code/Dockerfile
• test/e2e/live/mcp-bridge.test.ts
• src/lib/security/redact.ts
• src/lib/actions/sandbox/rebuild-durable-config.ts
• src/lib/actions/sandbox/rebuild-pipeline.ts
• src/lib/actions/sandbox/rebuild-dcode-preflight.ts
• docs/reference/commands.mdx
• docs/reference/commands-nemohermes.mdx
• src/lib/actions/sandbox/rebuild-managed-image-preflight.ts

[ericksoa]

Exact head b9801ff replaces the unrecognized CodeQL marker with the repository-proven lgtm[js/insecure-temporary-file] form immediately before the same read-only existing-directory open. The adjacent rationale and all O_DIRECTORY/O_NOFOLLOW hardening remain unchanged; 46 focused Dockerfile tests, Biome, both typechecks, hooks, and push checks pass.

PRA-1 disposition: the requested managed-OpenClaw MCP model-loop test is explicitly not applicable to this PR boundary. NemoClaw managed OpenClaw MCP remains the mcporter-only adapter merged in #5876, which writes the mcporter home registry. Pinned OpenClaw Tool Search reads native mcp.servers and enabled bundle catalogs; there is no production synchronizer between those ownership stores. A fixture-only native projection would falsely imply the shipped nemoclaw mcp path is model-visible. This PR intentionally leaves MCP configuration, bridge ownership, policy generation, CLI, and registry schemas unchanged. The committed pinned-runtime validator proves search, describe, and call for eligible hidden OpenClaw catalog tools; the existing live MCP scenario separately preserves mcporter credential rewrite, restart, rotation, rebuild, policy, DNS-rebinding, and secret-boundary proof. Combining those paths is a separate transactional dual-projection design requiring add/remove/restart ownership, rollback/crash consistency, config-hash and rebuild semantics—not a safe test-only change.

@coderabbitai review

[coderabbitai]

@ericksoa Understood on both counts:

• The switch to the lgtm[js/insecure-temporary-file] marker at the read-only existing-directory open, with the actual atomic-replacement file's O_CREAT|O_EXCL|O_NOFOLLOW/mode 0600/identity checks unchanged, is a reasonable, narrowly-scoped suppression.
• The PRA-1 disposition is clear: since the shipped managed OpenClaw MCP path is the mcporter-only adapter from #5876 with no production synchronizer into native mcp.servers/bundle catalogs, a fixture-only native projection would misrepresent what's actually shipped. The pinned-runtime validator (search/describe/call) plus the existing live mcporter scenario (credential rewrite, restart, rotation, rebuild, policy, DNS-rebinding) together cover the real boundaries here without conflating the two ownership stores.

Triggering a fresh review on exact head b9801ff6.

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[github-actions]

E2E Target Results — ✅ All selected jobs passed

Run: 28699693265
Workflow ref: feat/deepagents-progressive-tool-disclosure
Requested targets: ubuntu-repo-cloud-openclaw,ubuntu-repo-cloud-langchain-deepagents-code
Requested jobs: (default — all default-enabled free-standing jobs; explicit-only jobs openshell-gateway-auth-contract, mcp-bridge-dev, hermes-gpu-startup, sandbox-rlimits-connect, and jetson-nvmap-gpu are skipped unless selected)
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
live	✅ success

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28699904436
Workflow ref: feat/deepagents-progressive-tool-disclosure
Requested targets: (default — all supported)
Requested jobs: security-posture
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
security-posture	✅ success

[ericksoa]

Exact head e4214144c11dd47b9d3185f19c1c73ec4e690552 addresses the remaining review-body-only CodeRabbit nit: the Darwin fcntl fixture shim now fails with a targeted diagnostic when its exact injection anchor is absent, and a platform-independent regression locks that behavior. The focused suite passes 33 tests with one true Linux-only skip; Biome, CLI typecheck, repository checks, source-shape/test-size guards, commit hooks (with the known hanging local unsharded test-cli coverage hook skipped after its static/security gates), push hooks, and diff checks pass. Fresh exact-head sharded Linux CI is authoritative for the broad suite. @coderabbitai review

[coderabbitai]

Your plan includes PR reviews subject to rate limits. Reviews are available now.

[github-actions]

E2E Target Results — ❌ Some jobs failed

Run: 28699691367
Workflow ref: feat/deepagents-progressive-tool-disclosure
Requested targets: (default — all supported)
Requested jobs: onboard-resume,onboard-repair,cloud-onboard,inference-routing,hermes-e2e,rebuild-openclaw,rebuild-hermes,sandbox-rebuild,mcp-bridge,cloud-inference,openclaw-inference-switch,hermes-inference-switch,full-e2e,network-policy,security-posture,mcp-bridge-dev,hermes-gpu-startup
Summary: 16 passed, 1 failed, 0 cancelled, 0 skipped

Job	Result
cloud-inference	✅ success
cloud-onboard	✅ success
full-e2e	✅ success
hermes-e2e	✅ success
hermes-gpu-startup	✅ success
hermes-inference-switch	✅ success
inference-routing	✅ success
mcp-bridge	✅ success
mcp-bridge-dev	✅ success
network-policy	✅ success
onboard-repair	✅ success
onboard-resume	✅ success
openclaw-inference-switch	✅ success
rebuild-hermes	✅ success
rebuild-openclaw	✅ success
sandbox-rebuild	✅ success
security-posture	❌ failure

Failed jobs: security-posture. Check run artifacts for logs.

[github-actions]

E2E Target Results — ✅ All selected jobs passed

Run: 28700290435
Workflow ref: feat/deepagents-progressive-tool-disclosure
Requested targets: ubuntu-repo-cloud-openclaw,ubuntu-repo-cloud-langchain-deepagents-code
Requested jobs: (default — all default-enabled free-standing jobs; explicit-only jobs openshell-gateway-auth-contract, mcp-bridge-dev, hermes-gpu-startup, sandbox-rlimits-connect, and jetson-nvmap-gpu are skipped unless selected)
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
live	✅ success

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28700509914
Workflow ref: feat/deepagents-progressive-tool-disclosure
Requested targets: (default — all supported)
Requested jobs: security-posture
Summary: 1 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
security-posture	✅ success

[github-actions]

E2E Target Results — ❌ Some jobs failed

Run: 28700286465
Workflow ref: feat/deepagents-progressive-tool-disclosure
Requested targets: (default — all supported)
Requested jobs: onboard-resume,onboard-repair,cloud-onboard,full-e2e,hermes-e2e,mcp-bridge,inference-routing,rebuild-openclaw,rebuild-hermes,sandbox-rebuild,security-posture,openclaw-inference-switch,hermes-inference-switch,mcp-bridge-dev,network-policy,gpu-e2e
Summary: 15 passed, 1 failed, 0 cancelled, 0 skipped

Job	Result
cloud-onboard	✅ success
full-e2e	✅ success
gpu-e2e	✅ success
hermes-e2e	✅ success
hermes-inference-switch	✅ success
inference-routing	✅ success
mcp-bridge	✅ success
mcp-bridge-dev	✅ success
network-policy	✅ success
onboard-repair	✅ success
onboard-resume	✅ success
openclaw-inference-switch	✅ success
rebuild-hermes	✅ success
rebuild-openclaw	✅ success
sandbox-rebuild	✅ success
security-posture	❌ failure

Failed jobs: security-posture. Check run artifacts for logs.

[github-actions]

E2E Target Results — ✅ All requested jobs passed

Run: 28700286465
Workflow ref: feat/deepagents-progressive-tool-disclosure
Requested targets: (default — all supported)
Requested jobs: onboard-resume,onboard-repair,cloud-onboard,full-e2e,hermes-e2e,mcp-bridge,inference-routing,rebuild-openclaw,rebuild-hermes,sandbox-rebuild,security-posture,openclaw-inference-switch,hermes-inference-switch,mcp-bridge-dev,network-policy,gpu-e2e
Summary: 16 passed, 0 failed, 0 cancelled, 0 skipped

Job	Result
cloud-onboard	✅ success
full-e2e	✅ success
gpu-e2e	✅ success
hermes-e2e	✅ success
hermes-inference-switch	✅ success
inference-routing	✅ success
mcp-bridge	✅ success
mcp-bridge-dev	✅ success
network-policy	✅ success
onboard-repair	✅ success
onboard-resume	✅ success
openclaw-inference-switch	✅ success
rebuild-hermes	✅ success
rebuild-openclaw	✅ success
sandbox-rebuild	✅ success
security-posture	✅ success

e2e green, feedback addressed