Add deterministic read-only MCP invocation to managed Deep Agents Code

[jyaunches]

Problem Statement

Remy installation qualification requires one exact, read-only MCP task-context call before installer-owned completion can continue. The managed Deep Agents Code runtime cannot make that call deterministically.

NemoClaw adds progressive MCP tool disclosure to the pinned deepagents-code==0.1.55 package. In progressive mode, the task-context tool is registered for execution but hidden until the model discovers it. Direct mode exposes the tool, but neither mode requires invocation. Two real managed runs exited 0 without an MCP call or attestation, including a run whose prompt named the exact prefixed tool.

The sanitized failure marker was:

[remy-stack] managed-worker-qualification failure subject=worker.1 stage=handoff-missing status=succeeded returncode=zero task-context=absent handoff=absent output-handoff=absent

PR #6251 owns progressive disclosure. It does not provide mandatory or deterministic tool invocation. Searches found no issue or pull request that owns this contract.

Desired Behavior

The NemoClaw-managed Deep Agents Code image provides a headless command that calls one exact, coherently read-only MCP tool without model participation. The initial command shape is:

printf '%s' '{"task_id":"worker.1"}' | dcode tools call-read-only worker-broker_worker_task_context --json

The command must:

• use the real Deep Agents Code MCP configuration, discovery, tool wrapper, and executor path;
• select one exact resolved tool name;
• require the DCode MCP marker and coherent protocol annotations: literal readOnlyHint=true, no destructiveHint=true, and Boolean values for every supplied standard hint;
• parse one bounded JSON object from standard input;
• invoke the exact tool once without a model request;
• enforce one fixed producer-owned deadline across discovery, invocation, and
  cleanup, with a content-free timeout error;
• emit a bounded structured success result;
• preserve the MCP structured result under a fixed structured_content field,
  including the exact nested qualification.output_attestation value;
• emit exactly one bounded JSON envelope on standard output and no child or MCP
  diagnostics on standard error;
• exit nonzero with a bounded, redacted structured error for every denied or failed state; and
• close every MCP session and child process before exit.

Absent, duplicate, non-MCP, unannotated, malformed, contradictory, mutating, failing, oversized, and malformed-result cases must fail closed. The command must not expose a generic mutating MCP call surface.

Scope and Exclusions

Included:

• the NemoClaw exact-version patch for the managed deepagents-code==0.1.55 image;
• command parsing and help for the managed DCode command;
• deterministic MCP discovery, validation, invocation, result bounds, error redaction, and cleanup;
• focused source-shape tests and a build-time regression that runs the actual patched DCode process against an actual local MCP server; and
• exact managed-image publication and a later stable NemoClaw tag for Remy admission.

Excluded:

• prompting a model to choose or call the tool;
• forced first-turn tool_choice behavior;
• arbitrary or mutating MCP invocation;
• Remy ledger, handoff, installer-completion, retry, or worker-sequencing logic;
• changes to OpenShell MCP policy or credential delivery; and
• retrying the blocked v0.0.109 host.

The long-term general command belongs upstream in langchain-ai/deepagents. The first producer fix belongs in NemoClaw because this repository owns the managed DCode patch and image that the blocked consumer admits. Remove the managed patch when a pinned upstream DCode release provides an equivalent contract and the same regressions pass.

Ongoing Ownership

The NemoClaw maintainers who own agents/langchain-deepagents-code maintain the managed patch, image validation, and release propagation until the pinned upstream package provides the same behavior.

Placement and Support Expectations

Place this contract in core NemoClaw as a managed Deep Agents Code image capability. It is required by a current managed scenario qualification consumer. It does not define a general NemoClaw MCP mutation interface.

Validation Plan

• Patch the exact deepagents-code==0.1.55 package.
• Start an actual local Streamable HTTP MCP server from the installed MCP SDK.
• Run the actual patched dcode process with progressive disclosure enabled.
• Require the exact read-only task-context tool to run once and return bounded structured JSON.
• Require lossless qualification.output_attestation fidelity under the public
  response schema, bounded standard output, and empty standard error.
• Prove that the result does not depend on prompt wording or model compliance.
• Prove that absent, wrong, duplicate, non-MCP, unannotated, malformed-hint, contradictory, mutating, nonzero, oversized-input, oversized-output, and malformed-result states exit nonzero.
• Prove that no denied case invokes the tool.
• Prove that MCP sessions and child processes close after success and failure.
• Prove with a real hanging MCP tool that the command exits within its fixed
  call-and-cleanup deadline and returns only the stable timeout envelope.
• Preserve the existing progressive and direct disclosure regressions.
• Build the managed Deep Agents Code image from the changed Dockerfile and run the repository PR validation.

Compatibility Requirements

• NemoClaw managed Deep Agents Code image with deepagents-code==0.1.55.
• OpenShell v0.0.101 or later without an OpenShell contract change.
• Progressive and direct tool-disclosure modes.
• Linux managed-image architectures that the existing Deep Agents Code image workflow publishes.
• Remy must consume a new exact stable NemoClaw tag and its corresponding managed image. v0.0.109 remains ineligible for retry.

Security or Privacy Impact

The command crosses the managed DCode-to-MCP execution boundary. It must preserve DCode MCP configuration trust, environment resolution, transport authentication, and session cleanup.

The new authority is limited to one caller-selected tool that DCode already discovered and marked as MCP. Coherent read-only annotations are mandatory. The command rejects mutating or ambiguous tools before invocation. Input and output are bounded. Errors do not include tool arguments, MCP result bodies, resolved environment values, credentials, or credential paths.

No credential values or private host access are included in this issue.

Implementation Idea

Extend the existing dcode tools command through NemoClaw's exact-version package patch. Reuse resolve_and_load_mcp_tools, is_mcp_tool, mcp_tool_is_coherently_read_only, the real wrapped tool invocation path, and MCPSessionManager.cleanup. Add one installed-image validator with a local Streamable HTTP MCP server instead of creating a second MCP client or executor.

Category

Feature

Checklist

• I searched existing issues and this is not a duplicate.
• I described the problem and desired behavior.

[jyaunches]

Maintainer scope decision

Core NemoClaw placement is accepted for dcode tools call-read-only TOOL --json in the NemoClaw-managed DCode image. The current consumer is Remy worker qualification.

• Ownership: Maintainers for agents/langchain-deepagents-code own the wrapper, exact-version compatibility, validation, and release propagation.
• Compatibility: The supported contract covers Deep Agents Code 0.1.55, OpenShell 0.0.101 or later, both tool-disclosure modes, and the published Linux managed-image architectures.
• Security boundary: The command uses the integrity-bound managed MCP configuration, authentication, and network policy. It requires one exact MCP tool with coherent read-only annotations, bounds input and output, redacts errors, enforces a fixed deadline, cleans up sessions, and exposes no mutating command.
• Validation: The image build runs the patched DCode process against a local TLS Streamable HTTP MCP server. It covers allowed, denied, malformed, failed, oversized, ambiguous, timed-out, and cleanup behavior. Managed-image CI validates published architectures.
• Removal lifecycle: Remove the NemoClaw command when a pinned upstream release provides an equivalent deterministic command and the same installed-image validation passes through the upstream path.

This decision accepts the core placement and lifecycle proposed in #9889. A server's readOnlyHint does not independently prove its behavior; the configured MCP server's integrity remains part of the security boundary.