Add policy engine and human-in-the-loop approvals

Sensitive actions now stop for a human. Every tool call runs through the policy
engine, which allows it, denies it, or holds it for approval. Workspaces can set
their own rules per tool - always ask, auto approve, or never allow.

When an action needs approval the run pauses, keeping a snapshot of where it was,
and an entry shows up in the approval inbox with the exact tool and arguments.
Approving runs the action and lets the agent carry on from where it paused;
rejecting sends it back so the agent can pick something else. Approvals can
expire and can be limited to a role, and only people with approve rights can
decide.

Adds the approval model and migration, the inbox endpoints, and writes every
policy decision to the audit log.

Author: sanmaxdev

.env.example

@@ -49,3 +49,5 @@ RUN_MAX_WALLCLOCK_SEC=600
 AGENT_RUN_INLINE=false
 # When true, document ingestion runs inline instead of via a Celery task (tests/dev).
 KB_INGEST_INLINE=false
+# How long a pending approval stays valid before it auto-expires (0 = never).
+APPROVAL_TTL_HOURS=24

PROGRESS.md

@@ -11,7 +11,7 @@ Tracks build progress against the phases in `LEGATE_AGENT_BUILD_PLAN.md` (Sectio
 | 2     | LLM layer and Agent Core               | ✅ Complete    |
 | 3     | RAG knowledge layer                    | ✅ Complete    |
 | 4     | Connector framework and credential vault | ✅ Complete    |
-| 5     | Policy Engine and approvals            | ⬜ Not started |
+| 5     | Policy Engine and approvals            | ✅ Complete    |
 | 6     | Workflow engine and triggers           | ⬜ Not started |
 | 7     | Dashboard UX                           | ⬜ Not started |
 | 8     | Enterprise hardening                   | ⬜ Not started |
@@ -106,9 +106,26 @@ Tracks build progress against the phases in `LEGATE_AGENT_BUILD_PLAN.md` (Sectio
 - One credential per connector (1:1); multi-account per type and per-connector tool disambiguation are future work.
 - Webhook, Stripe, and Database connectors are deferred to later phases.
 
+## Phase 5 — Policy Engine and approvals ✅
+
+**Done**
+- Full Policy Engine (`legate/policy/engine.py`): `allow` / `deny` / `require_approval`, with per-workspace approval rules (`auto_approve` / `deny` lists) read from `workspace.settings_json`.
+- `Approval` model (+ `ApprovalStatus` enum) and Alembic migration.
+- Suspend/resume in the runner: on `require_approval` it snapshots the transcript into an `Approval`, sets the run to `waiting_approval`, and stops; `AgentRunner.resume` rebuilds the transcript and continues — executing the action on approve, or feeding a rejection observation back to replan on reject.
+- Approvals inbox API: `GET /approvals`, `GET /approvals/{id}`, `POST /approvals/{id}/approve|reject`. Deciding requires `approvals:decide`; resume dispatches inline (tests) or in the background (prod).
+- Expiry (`APPROVAL_TTL_HOURS`) with auto-expire on read/decide; optional per-approval role gate; `409` on expired or already-decided approvals.
+- Every policy decision audited (`policy.deny` / `policy.require_approval` / `policy.auto_approve`) plus `approval.approve` / `approval.reject`.
+
+**Acceptance:** an agent attempting a sensitive action is paused; an authorized approver approves it from the inbox and the action then executes; rejection resumes the run so the agent replans; an unauthorized user cannot approve; all decisions are audited. Verified by policy-engine unit tests and a full approval-flow suite (suspend / approve+execute / reject+replan / RBAC / expiry / double-decide / auto-approve / tenant isolation / audit), plus a 28/28 live-server smoke run.
+
+**Decisions / TODOs**
+- Reject resumes the run so the agent can replan (rather than hard-stopping); a "reject-and-cancel" option can be added later.
+- Approval expiry is evaluated lazily (on read/decide); a Celery-beat sweep for proactive expiry is a later addition.
+- `required_role` is stored and enforced when set; the UI to set it arrives with the dashboard.
+
 ---
 
-## Next: Phase 5 — Policy Engine and approvals
-Full allow/deny/require_approval rules, `Approval` model + inbox API, suspend/resume
-around approvals, per-workspace approval rules, expiry and role-gated approvals, and
-a full audit of every policy decision.
+## Next: Phase 6 — Workflow engine and triggers
+Workflow model + graph executor, node executors (trigger/agent/tool/condition/
+transform/approval/delay), sandboxed `{{ }}` templating, manual/schedule/signed-webhook
+triggers, pause/resume for approval nodes, and per-node retry with backoff.

apps/api/legate/agent/enums.py

@@ -30,3 +30,16 @@ class StepType(str, Enum):
     TRANSFORM = "transform"
     APPROVAL = "approval"
     TRIGGER = "trigger"
+
+
+class ApprovalStatus(str, Enum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    REJECTED = "rejected"
+    EXPIRED = "expired"
+
+
+#: Approval statuses that are final.
+DECIDED_APPROVAL_STATUSES: frozenset[ApprovalStatus] = frozenset(
+    {ApprovalStatus.APPROVED, ApprovalStatus.REJECTED, ApprovalStatus.EXPIRED}
+)