[Ross Nichols (rossnichols)]

📖 Description

Windows administrative policy can refuse native ProcessContainer creation.
Applications need machine-readable reasons and reusable permission-reduction
logic, but must be able to inspect the actual proposed permissions before
deciding whether to execute a task.

This documentation-only PR specifies policy preparation separately from execution.
Strict creation returns fresh structured PolicyFailures where Windows
supports reporting. A new additive V1.Dev preparation operation takes request
JSON, observations and separate extensible options, returning a complete
candidate request plus exact structured changes without creating a container,
starting traces or executing a workload. The caller inspects, accepts, edits
or rejects the candidate, then submits only its chosen JSON through ordinary
strict creation.

Existing V1 creation APIs and options, including Rust V1.Dev struct literals
and lifetime-free options storage, remain supported. The application owns
observation storage, checked whole-batch merging, acceptance and retry limits.
There is no transformation inside creation, automatic retry, private cache,
observation-input CLI option or policy-specific warning text.

The feature design and cross-SDK API proposal define preparation signatures,
candidate/change JSON, required before/after values, JSON Pointer semantics,
named native codes, storage/input limits and failure ownership. Their
validation plan covers nonempty preparation through real SDK bindings,
caller rejection and acceptance, strict filesystem enforcement, cwd/stdin,
fresh request/creator reuse, compatibility, source-generated JSON and AOT.
It distinguishes trusted native-attempt counts from workload sentinels and
requires actual filesystem enforcement through the SDK/native bindings.

Approval status: the feature design and cross-SDK API have been approved,
both documents are marked Accepted, and #1634 records the accepted scope.
MXC can depend on the Windows policy-result API when runtime detection finds
the getter and advertised reporting support. This PR changes the specification;
implementation delivery remains separate.

🔗 References

Refs #1634

• Feature design
• Cross-SDK API proposal
• Exploratory policy-preparation prototype
• Prototype Rust caller and acceptance example
• Feature contribution workflow

🔍 Validation

• Checked both documents against the feature/API templates, relative links
  and anchors, JSON examples, and the published prototype's Rust/.NET/Node
  declarations and storage contracts: passed.
• git diff --check: passed.
• Runtime tests were not rerun for this documentation-only update. The
  specification retains public preparation/strict-creation functional cases,
  injected native-error coverage, and the existing ProcessContainer CI path.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• For features or changes requiring a spec: linked the issue with maintainer-applied feature-accepted
• For implementation: linked the required approved and merged design/API spec, or explained why no spec is required
• Feature issue remains open unless this PR completes all agreed implementation, validation, and documentation
• Updated documentation (if applicable)
• Updated Copilot instructions (if build, architecture, or conventions changed)
• If this PR changes Cargo.lock, the dependency-feed-check check passes (see pull request builds)

📋 Issue Type

• Bug fix
• Feature
• Task

Microsoft Reviewers: Open in CodeFlow

[azure-pipelines]

Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

[Copilot]

🔵 Needs a closer look

The security-sensitive design requires maintainer and Windows-owner decisions on Rust API placement, experimental OS-contract shipping criteria, and a maintained governed x64/ARM64 CI fixture.

No open issues 🎉

What changed in this PR

This documentation-only PR proposes ProcessContainer creation-policy diagnostics and caller-authorized restrictive correction for #1634. Scope acceptance and design/API approval remain pending; no runtime behavior changes are included.

Changes:

• Defines strict-by-default diagnostics, bounded prelaunch correction, resource cleanup, and backend exclusions.
• Proposes compatible Rust, .NET, and Node controls that compose with writable stdin.
• Outlines governed-host functional validation and unresolved API, Windows support, and CI requirements.

File	Description
docs/​development/​architecture/​designs/​1634-creation-policy-correction/​README.md	Proposes feature behavior, security constraints, recovery, and validation requirements.
docs/​development/​architecture/​designs/​1634-creation-policy-correction/​api.md	Proposes cross-SDK signatures, examples, compatibility guarantees, and ownership semantics.

_{Review effort: Balanced}

[Gudge (MGudgin)]

Better diagnostics for administrative-policy refusals would be valuable. However, I think we should scope this feature to explaining the refusal, leaving policy changes and resubmission to the caller.

MXC understands the native failure and how it relates to the requested permissions. It does not know which permissions are essential to the caller's task. For example, reducing a writable directory grant to read-only may satisfy administrative policy while making the intended operation impossible. A restrictive change is not necessarily an acceptable change, and a blanket mutation opt-in does not express that distinction.

The responsibility split should be:

• MXC: retrieve and validate native policy diagnostics, preserve the original failure, and explain the conflicting permissions.
• Caller: decide whether a reduced request still meets its needs, make any changes, and explicitly resubmit.

With that boundary, I would remove automatic correction, retries with modified policy, cached restrictions, and the associated mutation options from this proposal.

The API design should instead focus on how callers receive actionable refusal details. Structured diagnostics may be useful so applications can make their own decisions without parsing human-readable error text.

[Ross Nichols (rossnichols)]

Better diagnostics for administrative-policy refusals would be valuable. However, I think we should scope this feature to explaining the refusal, leaving policy changes and resubmission to the caller.

MXC understands the native failure and how it relates to the requested permissions. It does not know which permissions are essential to the caller's task. For example, reducing a writable directory grant to read-only may satisfy administrative policy while making the intended operation impossible. A restrictive change is not necessarily an acceptable change, and a blanket mutation opt-in does not express that distinction.

The responsibility split should be:

• MXC: retrieve and validate native policy diagnostics, preserve the original failure, and explain the conflicting permissions.
• Caller: decide whether a reduced request still meets its needs, make any changes, and explicitly resubmit.

With that boundary, I would remove automatic correction, retries with modified policy, cached restrictions, and the associated mutation options from this proposal.

The API design should instead focus on how callers receive actionable refusal details. Structured diagnostics may be useful so applications can make their own decisions without parsing human-readable error text.

That was my original proposal for MXC, but it was rejected by our partners looking to consume this work - their main argument was that in their current architecture, sandbox management is not exposed to the agent loop, and doing so was prohibitively expensive. In follow-ups with Stuart, we decided on providing this opt-in API in MXC to satisfy these callers. I also prototyped an API for providing structured results rather than simple text, but I deferred that work in favor of first exposing the mutation within MXC itself. I do think it's worth bringing back as a follow-up, however.

[Copilot]

🟡 Changes recommended

The proposal breaks supported Rust V1.Dev compatibility, leaves conflicting caller contracts unresolved, and lacks an explicit combined feedback-and-writable-stdin validation requirement.

3 open issues

• Reconcile proposal scope with issue and PR description · New
• Require a live-process feedback and stdin acceptance test · New
• Preserve V1 compatibility for Rust JsonOptions · New

_{Review effort: Balanced}

[Gudge (MGudgin)]

Item 1 — SDK compatibility

The proposed Rust JsonOptions changes break existing V1.Dev callers: adding a field and #[non_exhaustive] prevents existing struct-literal construction, while adding a lifetime affects callers that store the options. V1.Dev is part of the supported V1 surface, so its name does not exempt it from compatibility requirements.

Please preserve the existing V1 types and signatures. An additive API in V1.Dev with a separate, extensible options type could provide the new functionality without breaking callers. In particular, the preparation operation suggested below could leave existing creation APIs untouched.

A V2 surface is another option, especially for broader SDK improvements, but this feature does not need to depend on it.

Item 2 — Separate policy transformation from execution

Thanks for revising this. Structured diagnostics, caller-owned storage, and explicit resubmission move the proposal in the right direction.

I also see the argument for sharing the transformation logic: multiple callers should not have to independently implement subtle permission-reduction rules. My remaining concern is coupling that transformation to execution.

Could we introduce an explicit preparation operation? Given a request and policy diagnostics, MXC would return a candidate restricted request plus structured details of the changes, without creating a container. The caller could inspect, accept, modify, or reject that candidate, then submit its chosen request through ordinary strict creation.

That keeps the difficult, reusable transformation logic in MXC while leaving acceptance of the resulting permissions with the caller. Applications could automate acceptance where appropriate, without making transformation and execution inseparable.

[Copilot]

🔵 Needs a closer look

Security-sensitive native Windows permission handling and new APIs require maintainer review, with experimental OS-contract release eligibility and governed-host CI fixture ownership still unresolved.

1 open issue

• Reconcile proposal scope with issue and PR description

2 resolved since last review

• Preserve V1 compatibility for Rust JsonOptions
• Require a live-process feedback and stdin acceptance test

_{Review effort: Balanced}

[Ross Nichols (rossnichols)]

🤖 Gudge (@MGudgin), the current revision addresses both your compatibility/preparation feedback and the earlier responsibility-boundary review.

Compatibility: existing V1 creation types and signatures, including Rust V1.Dev JsonOptions literals and lifetime-free storage, remain supported. The additions use separate extensible PolicyPreparationOptions under the corresponding Rust/.NET/Node V1.Dev entry points; this feature does not require V2.

Preparation versus execution: Rust prepare_policy_json, .NET PreparePolicyJson / PreparePolicyJsonAsync, and Node preparePolicyJson take request JSON and observations and return PreparedPolicyRequest containing candidate JSON plus exact structured changes. Preparation creates no container, starts no trace and runs no workload. The caller can inspect, accept, modify or reject the candidate, then submit only its chosen JSON through ordinary strict creation. MXC neither decides acceptance nor automatically retries or caches restrictions.

The revised feature design and API proposal, #1634, and exploratory prototype use that same contract. The proposal requires separate preparation/rejection/acceptance and strict run/spawn validation, including cwd/stdin and caller-owned merging. These changes are a proposal for review, not an assumption of scope, API or release approval.

[Copilot]

🟢 Approval recommended

No active review issues are recorded for this documentation-only design defining caller-owned policy preparation.

No open issues 🎉

1 resolved since last review

• Reconcile proposal scope with issue and PR description

_{Review effort: Balanced}