Scopes, approvals, and the ledger
The three mechanisms that decide what an agent can do in your community, what happens before a change lands, and what is left behind afterwards.
What a scope grants
A grant is a list of scopes on one community. There is no catch-all permission, no wildcard, and no implicit escalation between levels: holding community:moderate does not imply community:admin.
community:identityRead who the connected agent is acting as. Nothing about the forum itself.
community:readSearch topics, open threads, and summarize discussions. No writes of any kind.
community:writeDraft replies, propose tags, and flag content. Each one arrives as a proposal, not a change.
community:moderateRead the moderation queue and triage review items. Destructive triage waits for confirmation.
community:adminList members, change roles, create invitations, and update community settings.
Which tool needs which scope
A tool whose scope is missing from the grant is not listed to the agent at all. If it is called anyway, the call fails with a structured refusal rather than a partial result.
| Tool | Requires | What it does |
|---|---|---|
search_forum | community:read | Search topics and posts across the community. |
summarize_thread | community:read | Condense a long thread into its decisions. |
draft_reply | community:write | Propose a reply for a human to send or discard. |
propose_tags | community:write | Suggest tag changes on a topic as a diff. |
flag_content | community:write | Raise a post to the moderation queue. |
triage_moderation | community:moderate | Act on a review item, with confirmation. |
list_moderation_queue | community:moderate | Read what is currently awaiting review. |
list_community_members | community:admin | Read the member roster and roles. |
change_community_member_role | community:admin | Promote or demote a member. |
create_community_invitation | community:admin | Issue an invitation to a new member. |
update_community_settings | community:admin | Change community configuration. |
{
"code": "INSUFFICIENT_SCOPE",
"requiredScope": "community:moderate",
"trace": "9b21…04"
}Propose and approve
Write-class and moderate-class tools do not change the forum directly. They return a proposal: the current state, the proposed state, the scope used, and a trace identifier. A human with a sufficient role approves, edits, or rejects it.
Nothing in a proposal takes effect before approval, and rejecting a proposal is itself recorded. That means the ledger shows not only what the agent did, but what it wanted to do and was refused.
Approval authority follows role. A moderator can approve proposals made under community:write and community:moderate. Only an admin can approve one made under community:admin, and the roles are configured under Settings, then Members, as described in Running a community.
Reading the audit ledger
Every action, by an agent or a person, is written to the ledger once and is never rewritten. Each entry carries the actor, the scope it used, the target it touched, a trace identifier, the time, and the outcome.
actor: agent:moderator-7
scope: community:write
action: propose_tags
target: topic/4182
trace: 7f3a…c1
time: 14:22 GMT
outcome: approved by alice@acme.comThe ledger lives under Admin, then Audit in the community. Filter by actor, action, or target type. On the Team plan and above the full audit ledger history is retained.
The trace identifier is the thread to pull on. Every proposal, approval, refusal, and resulting change that belongs to one agent action shares the same trace, so a single identifier reconstructs the whole sequence.
A safe way to widen a grant
Start with community:read only and leave it there for a week. The agent can search and summarize but cannot write, so nothing it gets wrong reaches the forum.
Then add community:write and read the proposals for a while without approving many of them. The proposal queue is a low-risk way to evaluate an agent, because you see its judgment before it has any effect.
Add community:moderate only once the proposals are consistently worth approving, and treat community:admin as exceptional. Every scope you add is visible on the grant and revocable from your dashboard at any time.