Problem Statement
OpenShell policies are powerful, but users should not need to reason first in terms of low-level YAML, L4/L7 rules, binary scopes, and driver-specific guarantees.
For agent workflows, users think in modes:
- Can the agent only read?
- Can it write inside the workspace?
- Can it go online without review?
- Which actions require approval?
- Which policy changes can be auto-approved?
- Which guarantees are strong, best-effort, or unavailable on this driver?
OpenShell should define agent-oriented policy modes that compile down to the existing policy primitives and can be checked by deterministic validation where possible.
Parent: #1062
Roadmap context: #1038
Proposed Design
Define a small vocabulary of policy modes/safety levels, such as:
| Mode |
Meaning |
read-only |
Agent can inspect allowed local/network resources but cannot write externally. |
workspace-write |
Agent can edit workspace files, while external writes require review. |
reviewed-egress |
New external access must go through policy proposals. |
approved-online |
Known external services are pre-approved with scoped L7 rules. |
observe-only |
Activity is logged and analyzed without blocking, useful for policy discovery. |
These modes should not replace policy YAML. They should be product-level presets, explanations, and validation targets over the existing policy model.
Validation Model
Use a mix of deterministic and probabilistic review:
- Deterministic checks: policy prover, schema validation, scope classification, reachability checks, exfil/write-bypass checks.
- Reviewer judgment: AI reviewer or human reviewer evaluates intent, context, suspicious broadening, and whether the proposed capability makes sense.
The UI should separate these signals:
Prover: passed / failed / unknown
Reviewer: recommends approve / deny / needs human
Mode compatibility: compatible / broadens mode / violates mode
Auto-approval should only be eligible when deterministic checks pass and reviewer/human policy permits it.
Driver Capability Matrix
Modes must not overpromise isolation. For each driver/runtime, OpenShell should be able to explain whether a mode's guarantees are:
- strong
- best-effort
- unavailable
This matters for Docker, Podman, Kubernetes, microVM, and possible lightweight drivers such as bubblewrap or Apptainer.
Alternatives Considered
Require users to author raw policy YAML for every workflow posture.
This keeps the policy model explicit, but it makes common agent workflows harder to explain and compare. Users still need raw YAML for advanced cases, but product-level modes can provide safer defaults and clearer review semantics.
Treat reviewer-agent decisions as the policy mode.
Reviewer judgment is useful for intent and context, but it should not replace deterministic policy checks. Modes should define the intended boundary; prover/static validation should check what can be proven; reviewer paths should decide whether a requested change makes sense inside that boundary.
Agent Investigation
This follows the Policy Advisor roadmap umbrella in #1038 and the agent-driven policy management implementation track in #1062. It builds on the existing policy prover roadmap (#1059), deny-rule prover work (#1061), and reviewer-agent proposal issue (#1434).
Recent roadmap cleanup intentionally keeps #1038 as the customer-facing roadmap card while this issue tracks the concrete policy-mode design work underneath it.
Definition of Done
Problem Statement
OpenShell policies are powerful, but users should not need to reason first in terms of low-level YAML, L4/L7 rules, binary scopes, and driver-specific guarantees.
For agent workflows, users think in modes:
OpenShell should define agent-oriented policy modes that compile down to the existing policy primitives and can be checked by deterministic validation where possible.
Parent: #1062
Roadmap context: #1038
Proposed Design
Define a small vocabulary of policy modes/safety levels, such as:
read-onlyworkspace-writereviewed-egressapproved-onlineobserve-onlyThese modes should not replace policy YAML. They should be product-level presets, explanations, and validation targets over the existing policy model.
Validation Model
Use a mix of deterministic and probabilistic review:
The UI should separate these signals:
Auto-approval should only be eligible when deterministic checks pass and reviewer/human policy permits it.
Driver Capability Matrix
Modes must not overpromise isolation. For each driver/runtime, OpenShell should be able to explain whether a mode's guarantees are:
This matters for Docker, Podman, Kubernetes, microVM, and possible lightweight drivers such as bubblewrap or Apptainer.
Alternatives Considered
Require users to author raw policy YAML for every workflow posture.
This keeps the policy model explicit, but it makes common agent workflows harder to explain and compare. Users still need raw YAML for advanced cases, but product-level modes can provide safer defaults and clearer review semantics.
Treat reviewer-agent decisions as the policy mode.
Reviewer judgment is useful for intent and context, but it should not replace deterministic policy checks. Modes should define the intended boundary; prover/static validation should check what can be proven; reviewer paths should decide whether a requested change makes sense inside that boundary.
Agent Investigation
This follows the Policy Advisor roadmap umbrella in #1038 and the agent-driven policy management implementation track in #1062. It builds on the existing policy prover roadmap (#1059), deny-rule prover work (#1061), and reviewer-agent proposal issue (#1434).
Recent roadmap cleanup intentionally keeps #1038 as the customer-facing roadmap card while this issue tracks the concrete policy-mode design work underneath it.
Definition of Done