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 an organization-controlled security boundary. OpenShell has policy hot reload,
provider policy composition, and the policy.local proposal loop, but it does not have one
gateway-owned boundary that applies consistently to every way sandbox authority can change.

Product contract

Add one optional managed maximum policy at gateway scope. The maximum is a ceiling, not the
sandbox's active policy. It extends the existing OpenShell policy format rather than introducing
a second policy language:

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

The gateway must evaluate the fully composed candidate immediately before it creates or updates
a sandbox. The same admission decision must protect sandbox creation, policy revisions and
proposal approval, and provider changes. A narrower starting policy is valid; the maximum does
not grant access by itself.

When no maximum is configured, OpenShell keeps its existing unmanaged behavior.

Permission modes

The maximum declares which modes are available and the default for new sandboxes:

Mode	Agent-proposed authority inside the maximum	Review-required authority	Outside, denied, or unsupported authority
ask	Ask before applying	Ask before applying	Reject
auto	Apply automatically	Ask before applying	Reject

An authenticated user's direct policy edit is approval of that exact request, but it must still
fit inside the maximum. At creation time, review-required starting authority is rejected so it
cannot be granted silently; the response should identify what must be removed or reviewed.

auto automates approval of eligible proposals. It does not make the maximum 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:
    use existing unmanaged behavior

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 unsupported authority surface:
    reject with admin-required guidance

if the candidate exceeds the 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

Initial scope

• Configure one maximum policy with an ID, version, allowed modes, default mode, and optional
  review requirements. For the first implementation, it can be set, replaced, or deleted only
  when no sandboxes exist, and it does not coexist with the current global-policy override.
• Prove containment for L4 host/port/binary, REST endpoint method/path, GraphQL endpoint,
  operation, and root field, and remote MCP endpoint and tool authority.
• Enforce explicit denies before allows. Treat policy surfaces that the containment prover cannot
  model as unsupported and reject them in managed mode.
• Include provider-derived policy and credential-bearing reach in the candidate authority. Never
  log credential values.
• Return actionable decisions: apply, ask, or reject, with the maximum ID/version, mode,
  source, reason or counterexample, provider context, and candidate/delta hashes.
• Recompute against live policy and provider state immediately before apply. Stored proposal or
  approval evidence is explanatory, not authorization.

Review requirements belong to capabilities in the maximum policy, not to the source of a change.
The same write must require review whether it came from a policy proposal or provider attachment.

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 or MCP get_issue grant in auto mode	Apply
Propose a GitHub write or MCP tool marked review-required in auto mode	Ask
Propose any in-maximum grant in ask mode	Ask
Propose a denied DELETE, an outside-maximum grant, or an unsupported shape	Reject

Checked-in fixtures and examples should cover autonomous in-boundary work, read-auto/write-review
REST and GraphQL access, and read-auto/write-review MCP tools. Keep those examples runnable and
aligned with the implemented policy schema rather than embedding large YAML samples here.

Acceptance criteria

• A gateway administrator can set, inspect, and delete one managed maximum; no configured
  maximum preserves current behavior.
• Sandbox creation validates its mode and its fully composed starting authority, accepting a
  useful contained base policy and rejecting outside or review-required starting authority.
• One admission contract governs creation/provider attachment, direct and proposal-driven
  policy revisions, and authority-affecting changes to attached providers.
• ask and auto behave as described above; direct authenticated edits are bounded, and
  removals or no-op changes do not require approval.
• Containment, deny precedence, and review eligibility work for L4, REST, GraphQL, and remote
  MCP authority. Unsupported managed surfaces fail closed before approval logic.
• Pending changes are revalidated from live state before apply, so stale approval evidence
  cannot authorize a changed candidate, provider state, or maximum version.
• CLI/API responses and OCSF audit events explain the decision consistently, include enough
  identity and hash evidence to investigate it, and never expose secrets.
• Focused containment and admission tests plus one golden end-to-end flow demonstrate create,
  auto-apply, reviewed apply, rejection, hot reload/retry, provider composition, and audit
  output. Runnable REST/GraphQL/MCP examples ship with the feature.

Non-goals

• Live maximum-policy or permission-mode changes for existing sandboxes.
• A policy catalog, managed base-policy templates, tenant-specific maximums, or signed bundles.
• A new approval inbox or prompting on every use of authority already granted.
• Treating the maximum as permission to bypass the sandbox's active policy.
• Modeling policy surfaces beyond the L4, REST, GraphQL, and remote MCP scope above.

Existing work

• OpenShell Agent-Driven Policy Management #1062 provides the agent proposal and policy.local workflow.
• feat(policy): spike policy envelope and narrowness checks #1840 / PR feat(policy): spike policy envelope and narrowness prover #1843 provide the maximum-policy containment spike to reuse selectively.
• feat(prover): support deny rules in policy verification #823 covers deny precedence in containment.
• 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.