OpenShell Agent-Driven Policy Management #1062

Product Goal

OpenShell should provide an agent-driven policy management workflow that lets agents inspect current policy, draft narrow changes, and route them into a responsive reviewer inbox.

Roadmap context: #1038 is the public Policy Advisor roadmap card. This issue tracks the concrete MVP implementation for the agent-driven policy approval loop.

The core loop:

1. Agent attempts an action outside the current sandbox policy.
2. OpenShell denies the action with structured, agent-readable context.
3. Agent reads the local policy advisor skill and proposes the narrowest policy change it needs.
4. OpenShell stores the proposal as a draft policy chunk, not an immediate apply.
5. OpenShell runs deterministic control-plane validation and, when configured, control-plane AI/reviewer-agent review over the pending chunk.
6. A human reviewer or explicitly configured trusted reviewer path approves or rejects the chunk with optional guidance.
7. The sandbox hot-reloads the updated policy.
8. The agent wakes from /wait, observes the decision, and either retries or redrafts.

GitHub issues are the public development source of truth for this MVP. Earlier RFC/branch artifacts were planning notes and should not be treated as durable public references.

Locked MVP

• Single-sandbox TUI/CLI review flow.
• Structured L7 REST deny responses for agent-readable failures.
• Sandbox-local policy.local HTTP API.
• Agent-authored policy proposals stored as gateway draft chunks.
• Proposal payloads reuse the existing PolicyMergeOperation / incremental policy update shape.
• Static /etc/openshell/skills/policy_advisor.md documenting the policy.local workflow.
• Proposal provenance, validation status, returned chunk IDs, and rejection guidance.
• Gateway-side static/prover checks on agent-authored submit.
• Minimal review primitives for combining intent, formal checks, AI review, and approval policy (feat(policy): add review substrate and reviewer-agent approval path #1434).
• Control-plane AI/reviewer-agent review for submitted policy proposals (feat(policy): add review substrate and reviewer-agent approval path #1434), supporting advisory review and explicitly configured automatic approval/denial when approval policy permits it.
• /wait endpoint so agents can sleep on one long-lived request instead of polling or burning tokens.
• OCSF audit events for deny → propose → validate/review → approve/reject → reload → allow.

Non-Negotiable Trust Boundary

The proposing in-sandbox agent can submit policy proposals and read proposal outcomes. It cannot act as its own reviewer, directly approve or deny chunks, bypass the configured approval policy, or mutate live policy.

AI policy review belongs in the trusted OpenShell control-plane path, alongside gateway-side prover validation. A reviewer agent must evaluate structured proposal context from outside the proposing sandbox and record decisions through the same draft chunk approval/rejection paths as a human reviewer, with explicit provenance and audit events.

Automatic approval is in scope. The distinction is where the decision runs and under whose authority: small, well-scoped proposals may be approved at agent speed by configured control-plane review policy; broad, ambiguous, conflicting, or high-risk changes must remain human-required.

This is required MVP scope for a current, SOTA agent policy architecture: deterministic prover checks answer what can be mechanically verified; control-plane AI review provides contextual judgment over intent, suspicious broadening, and reviewer guidance. The UI must keep those signals distinct.

Simplicity Constraint

Keep the implementation small, inspectable, and easy to change while we learn. Prefer Sutton/Bitter-Lesson-friendly mechanisms: compute from the current policy, proposal, denials, and logs; give the reviewer concise context; store concise outcomes; iterate with replay fixtures.

Do not build a heavy evidence ontology, approval DSL, normalized review database, or service-specific intent taxonomy for the MVP. Reuse existing PolicyChunk/draft chunk fields, existing validation_result/rejection_reason style strings, and OCSF shorthand/log summaries where they are enough. Add new schema only when an experiment proves a value cannot be represented simply.

Review Primitive

The base primitive is broader than "AI approves policies":

A pending capability request is reviewed by small control-plane checks and reviewers that each return a concise verdict, and OpenShell applies a simple configured approval rule to decide approve, deny, or needs-human.

This lets us experiment with which actions can be automated through a combination of intent-based policy, formal methods, and AI review. The minimal shape should support:

• proposal context assembled from existing chunk fields, proposed operations, current policy, denied-request evidence, and short audit/log snippets;
• deterministic verdict text from schema/prover/scope checks;
• reviewer verdicts with only stable fields: decision, short reason, optional guidance, and optional evidence references;
• a small approval function or config, not a new policy language;
• provenance in existing approval/rejection/audit paths;
• replay fixtures for canned proposals so we can learn before adding structure.

Tactical Implementation Order

1. feat(gateway): persist and validate agent policy proposal operations #1097 — gateway prover validation. Populate deterministic evidence first: pass/fail/unknown, findings, scope classification, and any L7/L4 safety notes available today.
2. feat(policy): add review substrate and reviewer-agent approval path #1434 — minimal review primitives and control-plane AI reviewer. Use the existing ticket to avoid issue sprawl. Reuse existing chunks/logs, add the smallest reviewer verdict shape that supports advisory and automatic mode, and keep the approval logic readable code/config rather than a DSL.
3. feat(policy): suggest L7 scoping for known REST hosts #1099 — L7 scoping suggestion. Land with feat(gateway): persist and validate agent policy proposal operations #1097 or feat(policy): add review substrate and reviewer-agent approval path #1434 depending on where validation-result composition ends up.
4. feat(tui): render policy proposal inbox metadata #1098 — reviewer UX metadata. Render richer signals after they exist: prover result, AI reviewer recommendation, decision provenance, rejection guidance, and needs-human state. Keep single-sandbox MVP unless explicitly re-scoped.

Explicit Non-Goals For MVP

• Multi-sandbox push inbox / WatchProposals.
• Slack or web review adapters.
• Supervisor UDS policy API.
• In-process long-lived prover optimization.
• MCP server/tool wrapper. MCP can wrap policy.local later, but is not load-bearing for MVP.
• Heavy review/evidence ontology, approval DSL, service-specific intent taxonomy, or normalized review database.
• Unconfigured auto-approval, sandbox self-approval, org ceilings, or force-L7 enterprise policy.

Development Issues

• feat(policy): add agent-readable L7 deny body #1090
• feat(policy): write effective sandbox policy for local agents #1091
• feat(policy): expose sandbox-local policy.local API #1092
• feat(observability): enable OCSF JSONL for agent deny inspection #1093
• feat(policy): return draft chunk ids from policy proposal submit #1094
• docs(agent): ship static sandbox policy advisor skill #1095
• feat(policy): add proposal provenance, operations, and guidance fields to proto #1096
• feat(gateway): persist and validate agent policy proposal operations #1097
• feat(tui): render policy proposal inbox metadata #1098
• feat(policy): suggest L7 scoping for known REST hosts #1099
• feat(policy): add review substrate and reviewer-agent approval path #1434

Follow-Up Themes

• Agent-oriented policy modes and prover-backed safety levels.
• Multi-sandbox approval inbox.
• Pub/sub proposal updates.
• Documentation and examples for manual, advisory AI, and automatic reviewer policy loops.

Cross-Track Notes

• feat(prover): support deny rules in policy verification #1061 improves prover coverage for deny rules and is a dependency for stronger gateway validation.
• feat(policy): define agent-oriented policy modes and safety levels #1435 defines agent-oriented policy modes and safety levels; those should inform eligibility for future automatic reviewer decisions.
• #205 is closed; LLM-rationale enrichment remains future work. This MVP delivers the structured deny/proposal/reviewer loop, not an LLM PolicyAdvisor replacement.