Architecture Proposal: Granular RBAC (Role-Based Access Control) for Agents instead of Global Maintainer Trust

The problem

Hi team! 👋 First of all, amazing work on Facility. The concept of an open-source, observable AI SDLC platform is exactly what the industry needs right now.

While exploring the architecture, I noticed a significant security bottleneck regarding agent permissions. According to the current docs:

"Facility uses one maintainer trust model for every agent instead of per-agent permission profiles. A manifest cannot declare permissions..."

The Problem

While a global maintainer trust model is excellent for MVP velocity, it introduces severe security risks for enterprise adoption. If a repository has a specialized pr-reviewer.md agent, it currently inherits full write capabilities to the workspace and GitHub repository.
In the event of an LLM hallucination, or worse, a prompt injection attack from an external PR, a heavily scoped agent could execute destructive commands or expose sensitive environment variables.

What you propose

Proposed Architecture

To make Facility enterprise-ready, I propose introducing a granular Role-Based Access Control (RBAC) mapping for agents, heavily inspired by how GitHub Actions handles permissions.

1. Manifest Declaration: Allow .agents/*.md frontmatter to explicitly declare required scopes.
   ```yaml
   name: pr-reviewer
   engine: claude_code
   model: claude-3-7-sonnet
   permissions:
   pull-requests: write
   contents: read
   ```
2. Scoped Token Injection: Instead of passing the global GitHub App installation token to the agent's environment, Facility's API service can mint short-lived, scoped GitHub tokens specifically tailored to the agent's declared permissions for that exact turn.
3. Workspace/MCP Sandboxing: The MCP tools exposed to the agent can be dynamically filtered based on these permissions (e.g., blocking git push or specific MCP commands if contents: write is not present).

What you considered instead

Why this matters

As someone who architects autonomous AI workflows and multi-tenant SaaS platforms, the first question InfoSec teams ask before integrating AI into their SDLC is about blast radius containment. Granular permissions act as a necessary firewall between agents and the codebase.

I'd love to hear the core team's thoughts on this! Happy to help brainstorm the implementation approach for the services/api layer if this aligns with the roadmap.

Start with the current permission model in the documentation and inspect the services/api layer mentioned in the proposal. Trace how agent manifests, GitHub tokens, and MCP tools are currently handled. Done means the team has agreed on the scope and design for manifest permissions, scoped credentials, and tool filtering before implementation begins.