# PRD — Permission Relay · Workstream P

> **Status:** DRAFT for ratification · **Goals:** P1–P3 · **Design source:** `docs/3-architecture/guard-rails-capability-permissions.md` (old snapshot — "prepare freely, execute with approval")
> **Replaces:** Hermes `permissions_list_open` / `permissions_respond` relay (Hermes exit prerequisite, NS-13)

## Mission

A human-in-the-loop approval mechanism for agent actions: any capability listed as `requires_approval` is prepared by the agent, queued, and executed only after an explicit human approve — from the Matrix room or the webUI. Today this exists only as a design doc and a bare `applyGuardRails()` method; Hermes currently fills the gap and must be replaced before decommission.

## Requirements

### Guard-rails engine (P1)

| ID | Requirement |
|---|---|
| P-R1 | Capabilities are `resource:action` grants (e.g. `email:send`, `git:push_main`, `dns:update`) with permission levels (read / organize / draft / execute / admin) per the existing design doc. |
| P-R2 | Each integration declares its `requires_approval` list; grants are workspace-scoped and per-agent-persona. |
| P-R3 | Enforcement sits in the gateway/API dispatch path — an agent cannot bypass it by construction; bypass attempts are audited and denied. |
| P-R4 | Policy is configuration (profile field), honoring the configurability pillar: a user can tighten/loosen per capability without code change. |

### Approval queue + chat approvals (P2)

| ID | Requirement |
|---|---|
| P-R5 | A pending approval is a durable queue record: requesting agent, capability, human-readable intent summary, prepared payload reference, TTL. |
| P-R6 | Approve/deny from the Matrix room (message action or reply verb); the requesting agent is notified of the outcome and proceeds/aborts. |
| P-R7 | Timeout = deny (fail-closed). Deny and timeout leave the system unchanged. |
| P-R8 | Full audit trail: who approved what, when, from which surface (AC-NS-10). |
| P-R9 | The main agent (Jarvis) surfaces pending approvals conversationally (J-R13) but approval authority is the human's — Jarvis never auto-approves. |

### webUI surface (P3)

| ID | Requirement |
|---|---|
| P-R10 | Pending-approval queue view in `apps/web` with one-click approve/deny, filterable per workspace/agent (depends W3 dashboard shell). |

## Acceptance criteria

1. AC-NS-10 end-to-end: a `requires_approval` action executes only post-approve; deny/timeout paths verified unchanged + audited.
2. Approval round-trip from a phone Matrix client (Element) in under 3 taps.
3. With Hermes stopped, permission flow fully served by Mosaic (feeds AC-NS-11).

## Non-goals

- Automated quality gates (coordinator/CI approvals) — different system, already exists.
- Fine-grained LLM output moderation — out of scope; this governs *actions*.

## Assumptions

- ASSUMPTION: the durable queue rides the native Postgres storage service (same substrate as the backlog), not a new datastore.
- ASSUMPTION: routine delivery operations already hard-gated as no-confirmation (push/merge per Mosaic contract) are NOT routed through the relay — the relay is for `requires_approval` capabilities only, so it does not reintroduce routine confirmation prompts.