Permissions
The current foundation answers safe Discord liveness messages and has the first privileged admin surface:/permissions.
Use Bot Commands for command syntax, examples, responses, and failure cases. This page is the permission model reference.
Capability foundation is now present:
- guild owner and Discord
ADMINISTRATORcan receive admin override - role grants use Discord role IDs, not role names
- direct user grants are allowed for explicit exceptions
- missing identity, ambiguous identity, and missing capability fail closed
- audit events are validated so secret-looking metadata is rejected
/permissionslets authorized admins grant or revoke capabilities for a Discord role or user
/permissions is role-first:
role create: create a Discord role and grant a Gigi capability presetrole assign: assign a Discord role to a userrole unassign: remove a Discord role from a userrole grant: grant one capability to a rolerole revoke: revoke one capability from a rolerole grant-preset: grant multiple preset capabilities to a rolerole revoke-preset: revoke multiple preset capabilities from a roleuser grant: grant a direct user exceptionuser revoke: revoke a direct user exception
capability.manage. A Discord server administrator can bootstrap grants through admin override, then use Discord roles for normal access control. Direct user grants remain available for rare audited exceptions.
Role create, assign, and unassign require Discord server-level bot permissions. Being the only user in a channel, or being the person who runs the command, does not grant Gigi authority to edit roles.
If Gigi replies Could not update Discord role. Check Gigi has Manage Roles and role hierarchy is high enough.:
- open Discord server settings
- open Roles
- find Gigi’s bot role
- enable
Manage Roles - drag Gigi’s bot role above any role it must assign, remove, or manage
role create mainly needs Manage Roles. role assign and role unassign also depend on hierarchy: Gigi cannot assign or remove a role equal to or higher than its own highest role.
Future Discord slices should keep the earlier authority rule: surface is presentation, not authority. DM, slash commands, message commands, buttons, and external app triggers must resolve the same guild identity and capability model before doing work.
Planned Capability Shape
| Capability | What it allows |
|---|---|
plugin.install | Install or configure guild external app integrations |
plugin.run.<id> | Use an approved external app command or trigger |
capability.manage | Grant or revoke role/user capabilities |
job.admin | Inspect, retry, or cancel durable jobs |
job.read | List durable jobs through approved agent tooling |
job.schedule | Schedule allowed durable jobs through confirmation-gated agent tooling |
job.write | Cancel queued or failed durable jobs through confirmation-gated agent tooling |
web.search | Run capped public web searches through approved agent tooling |
web.fetch | Fetch capped public text or HTML content through SSRF-filtered agent tooling |
agent.analytics | View aggregate guild agent-runtime stats |
agent.reply_latency.manage | Enable or disable the guild reply latency footer |
memory.read.guild | Read permitted guild memory scope |
memory.manage.guild | Enable guild memory channels, configure retention, queue sync, and purge memory |
relay.dispatch | Ask Gigi to send a mediated message |
relay.receive | Receive mediated messages from Gigi |
llm.provider.write | Set, rotate, or delete guild-scoped provider credentials |
llm.provider.test | Test a guild-scoped provider credential without viewing it |
llm.provider.select | Choose active guild provider/model |
guild, user, and tenant credential owners. V0 exposes only guild-scoped provider credentials through the capabilities above. V1 can add personal BYOK, but a personal key pays for reasoning only; it does not grant plugin, memory, relay, job, or capability-management authority.
Presets
| Preset | Capabilities |
|---|---|
gigi-admin | capability.manage, plugin.install, job.admin, job.read, job.schedule, job.write, web.search, web.fetch, agent.analytics, agent.reply_latency.manage, llm.provider.write, llm.provider.test, llm.provider.select, memory.read.guild, memory.manage.guild |
plugin-manager | plugin.install |
job-operator | job.read, job.schedule, job.write |
web-reader | web.search, web.fetch |
llm-manager | llm.provider.write, llm.provider.test, llm.provider.select |
memory-reader | memory.read.guild |
memory-manager | memory.read.guild, memory.manage.guild |
relay-user | relay.dispatch, relay.receive |
Rules To Preserve
- Do not grant extra authority because the request came from DM.
- Do not grant extra authority because an external app created the command.
- Resolve guild, member, channel, role, and target user conservatively.
- Map capabilities by Discord role ID or user ID, never mutable role names.
- Prefer Discord role grants; use direct user grants only for rare exceptions.
- Keep external app permissions auditable by guild and manifest version.
- Keep sensitive actions private or confirmation-gated.
- Fail closed when identity or target resolution is ambiguous.
- Never expose raw provider credentials; provider keys are write-only.
- Do not silently fall back between guild, user, and tenant provider credentials.
- Do not let personal BYOK process guild context unless guild policy and the user explicitly allow it.
- Keep guild memory off by default and enabled per channel.
- Do not ingest DMs, private threads, group DMs, or deleted content into guild memory.
- Enforce channel visibility as well as
memory.read.guildbefore returning memory results.