Enterprise permission modes with managed maximum policies

[zredlined]

Problem

Enterprise deployments need to let agents start useful and evolve their access without letting
them exceed organization-controlled security boundaries. OpenShell has policy hot reload,
provider policy composition, and the policy.local proposal loop, but it needs one admission
contract that applies consistently to every way sandbox authority can change.

The older proposal-specific auto-approval and risk-query model also overlaps with managed maximum
admission. Keeping both would give reviewers and agents two different answers to whether a
capability may apply.

Product contract

Add gateway-managed maximum policy admission. A maximum is a ceiling, not the sandbox's active
policy, and it extends the existing OpenShell policy format rather than introducing another policy
language:

effective authority = sandbox policy + provider policy + credential reach + approved grants
candidate effective authority <= applicable managed policy envelope

The gateway evaluates the fully composed live candidate immediately before it creates or updates a
sandbox. The same admission decision protects sandbox creation, policy revisions and proposal
application, provider changes, and eventually agent/subagent policy composition.

A narrower active policy is valid; a maximum does not grant access by itself. Stored proposals and
prior approvals are evidence, not reusable authorization.

Workflow sequencing

This issue intentionally covers the broader end state, but the implementation is sequenced so the
core human and agent workflow can receive feedback before more policy-language complexity is added:

1. Establish the core managed-maximum workflow with filesystem, L4, and enforced REST containment,
   immutable ask or auto modes, provider composition, live-state revalidation, and one automatic
   admission surface.
2. Validate the core developer and reviewer experience in draft PR feat(policy): add managed maximum permission modes #2168.
3. Extend the same admission contract with GraphQL, remote MCP, and multiple policy inputs for
   agents and subagents. These are remaining phases of this issue, not separate non-goals.

The exact multi-policy API and composition rules can incorporate feedback from the core workflow,
but the organization-controlled maximum remains the outer authority boundary.

Permission modes

Gateway state	Agent-proposed authority inside the applicable maximum	Review-required authority	Outside, denied, or unsupported authority
No managed maximum	Ask	Ask	Existing unmanaged authority rules
Managed ask	Ask	Ask	Reject
Managed auto	Apply automatically	Ask	Reject

Without a managed maximum, accepted agent proposals remain pending for authenticated human review.
There is no separate unmanaged auto, yolo, or learn mode. A developer who wants hands-off
iteration can configure an explicit broad maximum and select managed auto.

An authenticated user's direct policy edit is approval of that exact request, but it must still
fit inside every applicable managed boundary. At creation time, review-required starting authority
is rejected so it cannot be granted silently.

Managed auto automates approval of eligible proposals. It does not make a maximum the active
policy or allow a denied runtime request automatically. Agents continue to use the existing
denial, proposal, wait, hot-reload, and retry loop.

Decision flow

if no managed maximum is configured:
    keep accepted agent proposals pending for human review

resolve all applicable managed policy inputs

if the requested permission mode is not allowed:
    reject

candidate = compose live sandbox policy, provider policy, credentials, and approved grants

if the candidate uses an authority surface not yet supported by containment:
    reject with admin-required guidance

if the candidate exceeds an applicable maximum or intersects an explicit deny:
    reject with a counterexample

if sandbox creation includes review-required authority:
    reject with review guidance

if this is sandbox creation, an authority removal/no-op, or a direct authenticated edit:
    apply

if mode is ask:
    ask

if the requested delta includes review-required authority:
    ask

apply

Credentialed raw-L4 advisory

Retain the useful observation behind the earlier L7-bypass finding as a non-gating advisory. Raw L4
authority to a host targeted by an attached provider credential records binary, host, and port
evidence because OpenShell cannot bound the stream by HTTP method or path.

The advisory never returns apply, ask, or reject and cannot override managed admission. To make
that authority require approval, mark the corresponding region review.required in the managed
policy.

Loopback, link-local, unspecified, and known metadata targets are different: OpenShell rejects
them as always-blocked network authority.

Target scope

• Configure managed maximum policy with identity, version, allowed/default modes, audit labels,
  and optional review requirements.
• Prove containment for filesystem paths; L4 host, port, and binary authority; REST method/path
  authority; GraphQL endpoint, operation, and root-field authority; and remote MCP endpoint/tool
  authority.
• Accept multiple applicable policy inputs so parent agents and subagents can be checked against
  their delegated policies while remaining inside the organization maximum.
• Enforce explicit denies before allows. Unsupported managed surfaces fail closed.
• Include provider-derived policy and credential-bearing reach in the fully composed candidate.
  Never log credential values.
• Return actionable apply, ask, or reject decisions with managed policy identity/version, mode,
  source, reason or counterexample, provider context, and candidate/delta hashes.
• Recompute against live policy, provider state, and applicable policy inputs immediately before
  apply.
• Keep initial maximum mutation constrained while sandboxes exist and preserve the
  proof-to-commit boundary under supported storage modes.

Review requirements belong to capabilities in managed policy, not to the source of a change. The
same write should require review whether it came from an agent proposal, provider attachment, or
subagent delegation.

Compatibility cleanup

• Remove proposal_approval_mode and sandbox create --approval-mode.
• Remove the empty-finding unmanaged auto-approval gate.
• Remove openshell policy prove and the legacy proposal-risk query model, registries,
  accepted-risk files, and findings.
• Preserve stale stored legacy approval settings as inert data.
• Keep credentialed raw L4 as advisory evidence rather than a second enforcement primitive.

Expected behavior

Request	Result
Start with a contained, auto-eligible base policy	Create the sandbox
Start with authority marked review-required	Reject with guidance
Propose a narrower GitHub GET, GraphQL query, or MCP read tool in managed auto	Apply
Propose a write or MCP tool marked review-required in managed auto	Ask
Propose any in-maximum grant in managed ask	Ask
Propose authority without a managed maximum	Ask
Propose a denied operation, outside-maximum grant, or unsupported shape	Reject
Propose credentialed raw L4 that is otherwise auto-eligible	Apply with advisory
Start a subagent with authority outside its parent or organization boundary	Reject

Checked-in fixtures and examples should cover autonomous in-boundary work, read-auto/write-review
REST and GraphQL access, remote MCP tools, and nested agent policy composition.

Acceptance criteria

• A gateway administrator can configure and inspect managed maximum policy without making it
  active sandbox policy.
• Sandbox creation validates its mode and fully composed starting authority.
• One admission contract governs creation, provider changes, direct and proposal-driven policy
  revisions, and agent/subagent policy composition.
• Unmanaged proposals require human review; managed ask and auto behave as described above.
• Containment, deny precedence, and review eligibility work for filesystem, L4, REST, GraphQL,
  and remote MCP authority.
• Multiple applicable policy inputs keep agents and subagents inside both delegated and
  organization-managed bounds.
• Unsupported managed surfaces fail closed before approval logic.
• Pending changes are revalidated from live policy, provider state, and applicable policy
  inputs before apply.
• Credentialed raw L4 remains advisory and cannot change admission.
• CLI/API responses and OCSF audit events explain decisions consistently and never expose
  secrets.
• Focused containment/admission tests and golden end-to-end flows demonstrate create,
  automatic apply, reviewed apply, rejection, hot reload/retry, provider composition,
  GraphQL/MCP behavior, nested policy bounds, and audit output.

Non-goals

• A new approval inbox or prompting on every use of authority already granted.
• Treating a maximum as permission to bypass the sandbox's active policy.
• A general policy catalog, signed policy bundles, or unrelated tenant-management UX.
• A contextual or LLM reviewer that becomes another enforcement boundary.

Existing work

• Draft implementation: PR feat(policy): add managed maximum permission modes #2168.
• OpenShell Agent-Driven Policy Management #1062 provides the policy.local proposal and wait/retry workflow.
• feat(policy): spike policy envelope and narrowness checks #1840 / PR feat(policy): spike policy envelope and narrowness prover #1843 provide earlier containment-spike context reused selectively.
• feat(prover): support deny rules in policy verification #823 covers deny precedence.
• feat(policy): revalidate pending policy proposals when effective policy changes #1636 covers stale proposal and approval revalidation.
• feat(policy): add review substrate and reviewer-agent approval path #1434 provides the reviewer substrate.

[armorer-labs]

This is a solid split between the org ceiling and the sandbox's active policy. The invariant I would make especially explicit in tests is that every authority-changing path is evaluated against the same candidate effective policy, not just the direct policy-update path.

A few edge cases worth pinning down early:

• compute candidate_effective_policy after provider-derived layers and credential reach are attached, because provider install often expands authority without looking like a policy edit;
• bind each decision to max_policy_id, max_policy_version, mode, candidate_policy_hash, and the requested delta hash, so stale approvals cannot be replayed after the ceiling or provider profile changes;
• treat review-required as a property of the matched maximum-policy capability, not of the proposal source, so the same REST/GraphQL/MCP write asks whether it came from a user edit, an agent proposal, or provider attachment;
• make unsupported prover surfaces fail closed before the ask/auto branch, otherwise unsupported-but-in-maximum shapes can accidentally turn into human-approved bypasses;
• add a negative test where an already-pending in-maximum proposal becomes outside-maximum after hot reload and must be re-evaluated before apply.

That keeps auto as bounded grant evolution inside a versioned ceiling, rather than a second place where authority can drift.

Disclosure: I work on Armorer Labs.

[zredlined]

Roadmap cleanup note: this issue is now the GitHub anchor for managed maximum policy and governed permission modes.

Implementation should reuse the completed spike work from #1840 / PR #1843 where helpful, but land through a production implementation branch for this issue rather than the spike PR. Direct supporting work to keep in view:

• feat(prover): support deny rules in policy verification #823 for deny-rule precedence in prover containment.
• feat(policy): revalidate pending policy proposals when effective policy changes #1636 for stale proposal / approval revalidation when policy, provider, credential, or max-policy baselines change.