[Feature]: Per-sender RBAC for multi-tenant agent deployments

[metalmon]

Summary

Add optional per-sender role-based access control so a single ZeroClaw instance can serve multiple user classes (customers, operators, developers) with isolated workspaces, tool sets, rate limits, and system prompts.

Problem statement

ZeroClaw currently runs with a single security policy for all users. When deploying an agent accessible via channels (Telegram, Discord, etc.), every sender gets the same tools, model, rate limits, and workspace. This makes multi-tenant deployments impractical:

• A customer-facing sales agent should have read-only product tools and a friendly prompt, but should not access shell, file writes, or internal docs.
• An operator/owner should see all conversations, manage the system, and use a more capable model.
• A developer should have full access with debug tools.

Today, achieving this requires running separate ZeroClaw instances per role, which multiplies infrastructure cost and prevents cross-role features like deferred task delivery.

The existing security scaffolding (IamPolicy, NevisIdentity, WorkspaceManager) provides types and tests but is not yet wired into the agent loop, channel processing, or tool execution. This proposal fills that gap with a lightweight, config-driven approach that can bridge to the existing security types when they are connected.

Proposed solution

A new optional crate zeroclaw-rbac (~120 lines) plus minimal integration points:

Core concepts:

• RoleResolver — maps channel sender ID to a named role via config assignments
• RoleDefinition — per-role: autonomy level, allowed_tools, workspace, model_hint, rag_access, rate_limit_per_minute, cost_daily_limit_usd, memory_isolation
• WorkspaceSelector — maps role to workspace directory + per-sender memory DB path (SHA256-based isolation when memory_isolation = true)
• Each workspace has its own AGENTS.md serving as the system prompt for that role

Enforcement via decorator pattern (no upstream signature changes):

• RateLimitedProvider wraps Box<dyn Provider> — intercepts chat() for per-role LLM rate limiting
• RateLimitedTool wraps Box<dyn Tool> — intercepts execute() for per-role action rate limiting
• Tool filtering applied before run_tool_call_loop — only allowed tools passed in
• Multimodal path canonicalization applied before run_tool_call_loop
• HookRunner::with_role_context() embeds role info without changing hook signatures

Integration pattern:

// In RBAC branch (channel orchestrator, CLI loop, dispatch executor):
if let Some(ref rbac) = config.rbac {
    let resolver = RoleResolver::from_config(rbac);
    let selector = WorkspaceSelector::new(&base_dir, rbac);
    let role_ctx = resolver.resolve(&sender_id);
    let workspace_dir = selector.workspace_dir(&role_ctx);
    let memory_db = selector.memory_db_path(&role_ctx, &sender_id);
    let provider = RateLimitedProvider::wrap(provider, &role_ctx);
    let tools = filter_and_wrap_tools(tools, &role_ctx);
    let hooks = hooks.with_role_context(role_ctx.clone());
    // ... call run_tool_call_loop with upstream-identical signature
}

Config example (inside existing config.toml):

[rbac]
default_role = "buyer"

[rbac.roles.buyer]
autonomy = "readonly"
allowed_tools = ["product_search", "product_info", "web_search"]
workspace = "shared"
memory_isolation = true
rag_access = ["public"]
rate_limit_per_minute = 10

[rbac.roles.owner]
autonomy = "supervised"
allowed_tools = ["*"]
workspace = "owner"
memory_isolation = true
rag_access = ["public", "internal"]

[rbac.roles.developer]
autonomy = "full"
allowed_tools = ["*"]
workspace = "dev"
memory_isolation = false
rag_access = ["*"]

[rbac.workspaces.shared]
path = "shared"

[rbac.workspaces.owner]
path = "owner"

[rbac.workspaces.dev]
path = "dev"

[[rbac.assignments]]
sender = "${OWNER_TELEGRAM_ID}"
role = "owner"

[[rbac.assignments]]
sender = "${DEV_TELEGRAM_ID}"
role = "developer"

Unmatched senders fall back to default_role.

Key design decision: All RBAC code lives in if let Some(rbac) branches. The non-RBAC path is identical to upstream. The decorator pattern means run_tool_call_loop, execute_one_tool, and other upstream function signatures remain unchanged.

Non-goals / out of scope

• Replacing or modifying existing IamPolicy/NevisIdentity/WorkspaceManager types
• OAuth2/JWT authentication (Nevis SSO) — orthogonal, can coexist
• UI/dashboard for role management
• Cross-instance federation
• Agent output verification/quality checks (future work)

Alternatives considered

1. Extend upstream WorkspaceProfile with RBAC fields — rejected because WorkspaceProfile is filesystem-driven (profile.toml per workspace) while RBAC needs a centralized config mapping senders to roles. Adding sender-mapping to WorkspaceProfile would change its semantics.

2. Use IamPolicy with synthetic NevisIdentity — rejected because IamPolicy expects OAuth2 identity objects. Constructing fake NevisIdentity from channel sender IDs is a hack that misrepresents the auth model.

3. Multiple ZeroClaw instances — rejected because it prevents cross-role features (dispatch), multiplies infra cost, and can't share config.

Acceptance criteria

• Single config file defines roles, tool sets, rate limits, workspaces
• Channel messages are resolved to roles by sender ID
• Each role gets isolated workspace directory and memory DB
• Per-workspace AGENTS.md serves as system prompt for the role
• Tool filtering enforced before agent loop
• LLM and tool rate limits enforced per role via decorators
• Non-RBAC deployments are unaffected (feature is opt-in via [rbac] section)
• run_tool_call_loop signature unchanged from upstream
• All enforcement testable in isolation (decorator unit tests)

Architecture impact

• New crate: zeroclaw-rbac (leaf dependency, ~120 lines)
• New types in zeroclaw-api: RbacConfig, RoleDefinition, RoleContext, SenderRoleAssignment, WorkspaceDefinition
• Integration: zeroclaw-runtime/agent/loop_.rs, zeroclaw-channels/orchestrator/mod.rs (additive if let branches)
• Config: one Option<RbacConfig> field in Config struct

Risk and rollback

Risk: RBAC branches in agent loop and channel orchestrator could affect non-RBAC paths if not properly isolated.
Rollback: Remove [rbac] section from config — all RBAC branches become no-ops. Or revert the crate addition (single workspace member line).

Breaking change?

No

Relationship to existing security modules

This proposal is designed to be forward-compatible with the existing security scaffolding:

• When IamPolicy is wired into the runtime, RoleResolver can accept NevisIdentity as an additional identity source alongside channel sender IDs
• When WorkspaceManager is connected to the agent loop, WorkspaceSelector can delegate to it instead of doing its own directory resolution
• The decorator pattern (RateLimitedProvider, RateLimitedTool) is independent of identity source — it only needs a role name and limits

Implementation plan

This RFC covers the overall design. Implementation will be split into separate PRs:

1. RBAC types in zeroclaw-api + zeroclaw-rbac crate
2. Decorator-based enforcement: RateLimitedProvider, RateLimitedTool
3. Integration points in agent loop and channel orchestrator
4. Dispatch system for deferred agent-to-agent tasks (complements existing cron scheduler)

[singlerider]

@metalmon Can you review #5891 and see how you can fold these requests as feedback into that Issue?

[singlerider]

Also check #5890 .

[metalmon]

Thanks for pointing to #5891 — I see the overlap and want to make sure this proposal fits into the multi-agent roadmap rather than working in parallel.

How this relates to #5891 sub-issues

#2767 (Multi-agent routing) — this is the closest match. Our RFC directly addresses the core ask: route inbound channel messages to isolated agents with separate workspaces, sessions, and tool sets. The mechanism is config-driven sender→role mapping:

[[rbac.assignments]]
sender = "${OWNER_TELEGRAM_ID}"
role = "owner"

Unmatched senders fall back to default_role. Each role maps to a workspace with its own AGENTS.md, memory DB, and tool restrictions. This is effectively "multi-agent routing by sender identity."

#5502 (allowed_tools on AgentConfig) — we already have allowed_tools: Vec<String> per role, enforced before the agent loop via tool filtering. Happy to align the field name and semantics with whatever lands for #5502.

#5889 (compound config) — our [rbac.roles.*] and [[rbac.assignments]] sections are compound config. If there's a preferred pattern emerging from #5889, we can adapt.

Compatibility with the tracker's ordering

The tracker proposes: config surface → delegate fixes → tool restrictions → routing.

Our work touches steps 3 and 4. We don't modify delegate or swarm internals — the decorator pattern (RateLimitedProvider, RateLimitedTool) wraps the existing provider/tool interfaces without changing run_tool_call_loop or execute_one_tool signatures. So steps 1-2 can land independently.

One question: [rbac.*] vs [agents.*]?

Our config uses [rbac.roles.*] as the namespace. If the multi-agent initiative settles on [agents.*] as the canonical surface (#5891 acceptance criteria), we can restructure the config to fit under that namespace. The implementation is agnostic to config key names — it just needs a sender→role→workspace mapping.

Dispatch as complement to delegate/swarm

We also have a dispatch system (deferred agent-to-agent task delivery) that complements delegate and swarm rather than competing with them:

	Delegate	Swarm	Dispatch
When	Inline, synchronous	Parallel, fan-out	Deferred, async
Identity	Parent's context	Parent's context	Recipient's role context
Delivery	Return value	Aggregated results	Message bus injection into recipient's session
Retry	No	No	Yes (dispatch_defer tool)

This is a separate feature we'd propose independently, but mentioning it here for context since it builds on the same role resolution infrastructure.

---

Happy to adapt the proposal to align with the direction #5891 takes. Let us know if you'd prefer we restructure around [agents.*] or if the [rbac.*] namespace works as a routing layer alongside it.

[singlerider]

Adding this to the #5878 tracker for now so we don't lose it. I'll have to come back to re-evaluate. We have a weekly Discord call at 8PM, Eastern on Thursdays. That would be a great time to discuss this. You've got a big ambition in this Issue.

[Audacity88]

Related issues:

• feat(tools): session ownership model for destructive operations #5833 — session ownership model for destructive operations (per-agent scoping). RBAC's role resolver would provide the identity layer that session ownership needs.
• fix(discord): populate thread_ts for per-thread session isolation #5412 — Discord per-thread session isolation. RBAC's per-sender workspace selection addresses the same class of isolation gap.

[metalmon]

Thanks a lot for the invite and the pointer to #5878 — really appreciate that it's being tracked rather than dropped.

Quick note on the Thursday call: I'd love to join, but my conversational English struggles with fast-paced voice discussion, so I'd end up missing nuances. I'd much rather engage asynchronously on the issues — I can write detailed responses, and anything written gives me time to understand the context properly. If there's a summary or action items posted after the call, I'll respond quickly in writing.

Concrete next step I'd propose: let me draft a focused comment on #5891 that reframes this RFC as feedback under the multi-agent umbrella — specifically mapping our decorator-based enforcement to #2767 (routing) and #5502 (allowed_tools), and raising the [rbac.*] vs [agents.*] namespace question there so it's in the right thread.

Also happy to wait if you'd rather finalize the #5891 config surface first — I don't want to jump ahead of the ordering in the tracker. Just let me know the preferred sequence and I'll work to it.

Thanks again for taking the time to read through the proposal.

[metalmon]

Quick follow-up after going through #5891, #5890, and the adjacent work. Between the per-agent identity model in #5890, send_user_message/send_channel_message (#5611, #5145/#5152), the channel-based approval flow (#4534), background delegate plus await primitives (#4159, #5087), and per-agent allowed_tools (#5502), most of what this RFC raised has a home or is being actively shaped elsewhere. Rather than keep pushing design at this stage, we're going to stand by and let #5890 settle.

A few pieces of our fork — per-sender memory isolation within a single agent, per-role rate/cost caps, and a small defer_into_session primitive we use for self-scheduled polling of long-running MCP tools — don't obviously map onto an existing upstream issue yet. Parking them until the canonical shape lands. If any sub-issue under #5891 reaches a point where our fork's existing implementation would be useful as a starting point for a PR, happy to contribute that way instead of writing more design.

Thanks for taking the time on this — the #5891 ordering has been clarifying.