RFC: approval policy for external agents acting through the MCP server

[criptogus]

Summary

The embedded MCP server (Phase 2 P0 keystone in ROADMAP.md) exposes the same document tools as the AI panel (read_blocks, replace_blocks, propose_operations, slides/pdf tools) to any MCP client — Hermes, Claude Code, community agents. The trust pipeline (RFC #8) assumes a human in the loop: propose → preview → accept/reject. Headless agents cannot click "accept". Without an approval model, the MCP server is either an open mutation surface or a locked door nobody can use.

Context

• Trust track (ROADMAP.md, Phase 1): every mutation becomes a Proposed Change (RFC RFC: unified "proposed change" contract in agent-core #8), previewed and approved before apply.
• Embedded MCP server (Phase 2): external agents act on documents through the same pipeline.
• The contradiction: the approval UX is human-only; agents are headless.

Design questions

1. Approval policies — per-project policy objects, e.g. { "scope": "section 2", "agent": "@writer", "mode": "auto-approve" } or { "scope": "any slide", "mode": "always ask" }. Who can create/edit a policy (project owner, local admin)?
2. Deferred approval — for headless runs, proposed changes queue in a review inbox; the human accepts/rejects later, with a one-click "accept all from agent X in scope Y". Is deferred approval acceptable for agent workflows (CI-style), or must agents block on approval?
3. Trusted-agent mode — is there a "fully trusted" mode (a user-approved agent with declared permissions: which tools, which document scopes) where mutations apply directly but are always audited? Compare: OAuth scopes for agents.
4. Permission declaration — should the agent declare its permissions in the MCP handshake (manifest: tools + scopes), enforced server-side?
5. Audit — every mutation (approved or deferred) records: agent identity, the policy rule that allowed it, timestamp, diff. Should the audit trail live in the OOXML (agent authorship) or in project-store first?

Suggested direction (to challenge)

Per-project policy objects + agent-declared permissions at the MCP handshake + deferred approval queue for headless agents + mandatory audit. In-app human interactions keep the current propose → preview → apply UX unchanged.

Deliverable

This RFC resolves the design and produces the contract for the approval pipeline. Implementation is tracked separately (see the MCP server spike issue).

[renezander030]

Question 2 is the one that bites in practice: a deferred proposal is computed against a document revision at propose time and applied hours later, so the Proposed Change has to pin that base revision and the apply has to fail loudly when the document moved underneath it. Otherwise "accept all from agent X in scope Y" quietly writes diffs against blocks the agent never read.

Reference implementation of the propose/validate/approve path we run: https://github.com/renezander030/agent-approval-gate