Policy Engine & Approvals
Relevant source files
The following files were used as context for generating this wiki page:
The Policy Engine & Approvals system governs how Coral validates and authorizes agent tool calls. It acts as a gatekeeper between sandboxed TypeScript programs and external provider operations.
The system ensures that every call matches user-defined rules. You decide if an operation runs automatically, waits for manual approval, or remains disabled. If a call requires approval, the Program Run pauses until a human reviewer provides a decision.
Sources: README.md, apps/reef/app/views/providers/workspace-providers-page.tsx:132-138
Policy Configuration
Workspace owners manage policies at the provider and operation levels. The engine evaluates these rules whenever an agent attempts to execute an operation.
Policy States
Each operation exists in one of three primary policy states:
| Policy State | Behavior |
|---|---|
| Always allow | Coral executes the call immediately with stored credentials. |
| Approval required | The Program Run pauses. Coral creates an Approval Request for human review. |
| Disabled | Coral rejects the call. The program receives an operation_disabled error. |
Sources: README.md, apps/reef/app/views/providers/workspace-providers-page.tsx:64-106, apps/reef/app/views/activity/detail.test.tsx:112-118
Bulk Management
The Reef UI allows workspace owners to apply policies to multiple operations simultaneously. Selecting operations in the provider list activates the Bulk Policy Form. This form submits a SELECTED_OPERATION_FIELD containing encoded provider and operation identities to the policy action handler.
Sources: apps/reef/app/views/providers/workspace-providers-page.tsx:1037-1080
Approval Workflow
When a program triggers an "approval required" policy, the execution enters a parked state.
The Approval Lifecycle
The following diagram illustrates the lifecycle of a call requiring human intervention:
The workflow ensures that sensitive operations never execute without explicit consent.
Sources: AGENTS.md, README.md, apps/reef/app/views/activity/detail.test.tsx:1322-1355
Expiry and Timers
The Run Owner coordinates approval request deadlines. Every request has a specific expiry time. Timers fire as messages into the Run Owner's mailbox. If a request reaches its deadline before a decision occurs, the owner records the state as Expired. No external process polls the clock to decide expiry; the owner manages this state in memory to ensure atomicity.
Sources: AGENTS.md, apps/reef/app/views/activity/detail.test.tsx:1162-1175
Persistence and Consistency
Coral uses a shared database chain for migrations and strictly manages authorization fact rows.
The Dispatch Fence
Coral uses a "Dispatch Fence" to prevent stale policy decisions. Before dispatching a call, the system rechecks policy rules. It reads policy rows with RowLock::Shared (via Transaction::fetch_optional_locked). Other lifecycle decisions take an exclusive UPDATE hold on rows to prevent race conditions during concurrent program runs.
Sources: AGENTS.md
Transaction Choreography
Domain code owns the transaction choreography. Repository modules perform the actual queries and row mapping. The system returns typed evidence to domain callers rather than raw database rows. This boundary separates authorization logic from persistence encoding.
Sources: AGENTS.md
Review Interface
The review interface provides humans with the context needed to make authorization decisions.
Review Context
A reviewer sees specific metadata for every pending call:
- Call Path: The exact TypeScript signature of the operation.
- Arguments: The literal JSON arguments passed by the agent.
- Task Intent: The high-level goal the agent is pursuing.
- Requested By: The identity of the agent or user that initiated the run.
Sources: apps/reef/app/views/actions/review.test.tsx:288-315, apps/reef/app/views/activity/detail.test.tsx:75-95
Decision Handling
Decision forms submit a CSRF token, a request identity, and the chosen intent (approve or decline). Users may optionally add a comment. The system prevents duplicate or opposite decisions by disabling controls while a decision is pending. If a decision succeeds, it advances the review to the next pending action in the run.
Sources: apps/reef/app/views/actions/review.test.tsx:162-185, crates/coral-mcp/tests/credential_free_tracer.rs:1330-1345
The Run Owner ensures the first decision submitted for a specific request ID wins.
Sources: AGENTS.md, apps/reef/app/views/actions/review.test.tsx:220-235
Security Considerations
The Policy Engine enforces strict isolation for authorization data.
- Private Content: Program content and feedback stay out of traces and logs. Telemetry only captures non-sensitive metadata.
- Host Binding: MCP sessions bind to specific credentials and workspaces. A session on Workspace B cannot access or observe policy rules in Workspace A.
- Escaping: The system escapes dynamic values in the OAuth approval templates to prevent injection.
Sources: crates/coral-mcp/tests/credential_free_tracer.rs:1410-1425, crates/coral-mcp/tests/credential_free_tracer.rs:245-265
Policy Engine & Approvals provides the essential safety layer for autonomous agents. It combines database-level consistency with a high-fidelity human review process. By utilizing the Run Owner model and the Dispatch Fence, Coral ensures that every external call remains under the control of the workspace operator.
Sources: README.md, AGENTS.md