[RyaliNvidia]

What does this PR do?

Expose existing harness controls for custom system instructions and built-in tool selection. Pi and OpenCode gain system_prompt_mode: append | replace, retaining append defaults. Pi's enable_tools: false uses --no-builtin-tools while preserving separately granted MCP tools, output limits and outcome reporting.

OpenCode replacement explicitly selects build, keeps the user task separate and rejects conflicting --agent arguments. Local replacement uses a per-invocation config override, preserving sibling configuration without writing request-specific prompts into a persistent repository. Existing OpenCode tool selection, sandbox restrictions, plugins and continuation behavior remain intact.

Preserve injected replacement prompts literally through OpenCode's pre-JSON {env:...} / {file:...} substitution. Escape opening braces only in the serialized agent.build.prompt value, so JSON decoding restores the original text. Both local and sandbox paths share this handling. Intentional substitutions elsewhere—including identical text in another agent's prompt—remain active. Append mode and configurations without an injected replacement use ordinary serialization.

The branch incorporates main c69f3b15ff794d6cb49418117748bb16be195cbb, retaining its sandbox runtime changes, canonical package imports and documentation additions. No separate issue is needed for this focused exposure of existing native controls.

Validation

• Current-main necessity audit: the named prompt-mode and Pi built-in-tool controls are absent from main's config models and serialized config; supplied values are ignored. Main retains append-only prompt commands and ordinary JSON config serialization. No obsolete feature hunks were found.
• Both isolated adapter wrappers ran from independent environments installed from uv.lock --extra dev --extra sandbox through Gym's setup helper, then reused with ++skip_venv_if_present=true. Commands use gym env test +entrypoint=responses_api_agents/<pi_agent|opencode_agent> +should_validate_data=true. Pi: 335 passed, 27 skipped. OpenCode: 592 passed, 50 skipped on the complete repeat.
• The first parallel OpenCode run had 591 passed, 1 cleanup-error fixture failure, 50 skipped (Sandbox.params() raised KeyError('')). The unchanged case passed individually on both the PR and verified main; the complete unchanged repeat passed. No assertion or source was altered to obtain that result.
• Prompt-control and serialization suites: 15 passed, including 9 native CLI cases, using Pi 0.80.2, OpenCode 1.17.11, synthetic loopback services and isolated configuration. Tests cover replacement and tool selection in both execution paths, literal env/existing-file/missing-file references, Unicode, whitespace, quotes, backslashes and literal \\u007b text.
• Replacing only the prompt serializer with ordinary json.dumps makes both native literal regressions fail on the missing-file reference. Removing explicit build selection makes its native replacement regression fail because the replacement marker is absent. Normal substitutions in other configuration remain active.
• Independent verifier: 23 current-main MCP/plugin/deadline tests passed with replacement mode and literal template prompts enabled. Required-tool validation, failure recovery and continuation validation remain intact. Independent simplifier found no redundant production code.
• Public-import policy checks: 2 passed. pre-commit run --all-files, Ruff/format and PR-relative whitespace checks passed. The private guardwords scan was skipped because its catalog was unavailable.
• Fern validation passed with zero errors; its redirect-history check was skipped without authentication.

The merge from main was clean and required no manual source changes. Existing capture, task-tool staging, cancellation and continuation behavior remains. Earlier optional KiloCode conformance failures are outside this PR; incorporated main includes a later KiloCode fix. These local results do not claim a new-head CI result.

Compatibility and limits

Defaults preserve existing behavior. Replacement and tool selection are evaluation treatments and should be recorded. OpenCode replacement selects build even if another default agent is configured; append retains custom selection. Native environment context may remain, so replacement does not promise byte-identical whole model requests.

No new dependency, runtime image, authentication or retention change. Real harness checks use synthetic local model/MCP services; no live provider, remote sandbox, benchmark-quality or full-core qualification is claimed. New source carries Apache-2.0 SPDX headers and PR commits include DCO sign-off.

Proposed maintainer labels: feature, area:agent, needs-review.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[yaoyu-33]

One prompt-serialization issue below.

[RyaliNvidia]

/ok to test 0a67829

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-5144-39774fe62a3b.docs.buildwithfern.com/nemo/gym

[RyaliNvidia]

/ok to test 39774fe

[yaoyu-33]

Re-reviewed at 39774fe.

The earlier {env:...} / {file:...} thread is resolved. Only the injected agent.build.prompt is escaped, in both the local and sandbox paths, and substitutions elsewhere in the config stay active. I round-tripped _serialize_replacement_config on about 5,000 generated prompts (braces, backslashes, a literal \u007b, control and non-BMP characters): each decodes to the original text, and neighbouring keys, their order and sibling {env:...} / {file:...} text come through unchanged. I did not re-run the pinned-CLI cases locally.

The merge from main is clean and the branch still merges into current main without conflicts. CI is green apart from the non-blocking harness-conformance KiloCode job already noted in the description. No blockers or risks left from my side.

[github-actions]

🔄 Merge queue validation started! You can track the progress here: https://github.com/NVIDIA-NeMo/Gym/actions/runs/41513131179