RBAC and permission layers

HTTP and the governance surface are trimmed by role; tool execution has a separate allow / deny / ask rule set. Do not treat “having an approval desk” as a complete permission model.

Roles

Role	Capability summary
`admin`	Full access: breaker trip/reset, global config, org writes, retention manual scan, audit rehash
`operator`	Can chat/execute/trigger; cannot HITL decide; cannot write platform-level config/plugin; cannot trip breaker or run retention scan
`approver`	Rough operator superset, plus HITL decide; still cannot write org/global config or trip breaker
`readonly`	Safe read-only methods only (health checks and similar exceptions)

Legacy value ops is treated as operator. Header X-AgentForge-Role participates in resolution when identity is not bound; after binding, the account mapping wins. See Identity and tenant binding.

flowchart LR
  Req[HTTP request] --> Role[Resolve role]
  Role --> Gate[Route-level RBAC]
  Gate --> Exec[Business / tools]
  Exec --> Tool[allow/deny/ask]
  Tool --> Hitl[HITL when needed]

Relation to tool permissions

Role RBAC decides “may this kind of API be called.” Tool rules decide “may the model run this tool, and must a human be asked.” Patterns such as external directories are expressed via permission patterns — not a second HTTP role layer named Read/Write/External.

Role draft tiers (for example readonly / assist / operator) are job templates; they still resolve to the roles above and tool permissions. Product claim: permission isolation.

Related reading: