Reviewed channel permission overwrites

list_channel_permission_overwrites is a bounded read-only inventory under ordinary channel scope. It sorts exact role and member targets deterministically, pages with an exact target-ID cursor, names every known allow and deny bit, preserves arbitrary-width bitfields, and reports unknown future bits separately. A thread request returns the validated parent's overwrite set, the requested thread, the exact source channel, and explicit inherited evidence because Discord threads do not carry independent overwrites. The equivalent discord://channels/{channelId}/permission-overwrites resource template performs the same scoped read and never persists the result.

Changes have no immediate-call path. Set capabilities.permissionOverwrites: true and list every eligible direct guild channel by its own exact ID in scopes.permissionOverwriteChannelIds. The mutation allowlist must be a subset of readScope.channelIds when the read allowlist exists. Categories, text, announcement, forum, media, voice, stage, and directory channels are accepted; thread and direct-message mutation is rejected. Grant the bot channel-level VIEW_CHANNEL and MANAGE_ROLES in every selected target without granting ADMINISTRATOR.

1. Call plan_channel_permission_overwrite with the exact channel, exact role or member target, update or delete mode, Discord audit-log reason, and unique one-shot operation key. An update supplies unique named channel permissions with an allow, deny, or inherit state; deletion supplies no changes.
2. Review the verified application and bot IDs, exact guild, channel and target, current and desired overwrite, effective-access impacts, connector permissions before and after, parent-category synchronization, warnings, operation-key hash, and keyed digest.
3. If the action is none, the exact overwrite already has the requested state and no confirmation, reservation, activity record, or Discord write is needed.
4. Call execute_channel_permission_overwrite with identical inputs plus the digest.
5. Approve the signed MCP confirmation only if every exact identity, state transition, permission impact, synchronization warning, audit reason, operation-key hash, and digest remains intended.
6. Review the returned target overwrite, complete-set match, activity ID, and outcome before any follow-up.

Updates preserve every unspecified channel-scoped bit and can move a named permission among allow, deny, and inherit without exposing a raw-bitfield input. An update that produces empty allow and deny sets becomes an explicit reviewed DELETE. A requested delete removes the entire exact overwrite. Bulk reset, arbitrary category-copy, raw bitfields, channel creation, channel deletion, and automatic rollback are intentionally outside this workflow. Exact parent-category synchronization uses the separately gated reviewed synchronization workflow.

Planning verifies the application and bot identity, exact mutation scope, direct guild channel, guild owner, connector membership, complete bounded role inventory, full target overwrite set, optional parent category, and exact role or member target. Member targets require one exact member lookup rather than guild-member enumeration and reject the connector bot, guild owner, and configured protected users. The plan reports member-effective access or a standalone role baseline before and after for every changed permission. It also reports whether the channel exactly matches its parent category before and after, including a warning when the change breaks synchronization.

An update fails closed if the target overwrite carries unknown future bits or known permissions that are not channel-scoped, because rewriting its full bitfields could silently damage state the connector cannot safely represent. Explicit deletion remains available and warns when it will remove unknown bits. The connector must hold every permission placed in either outgoing bitfield and must retain both VIEW_CHANNEL and MANAGE_ROLES under the complete prospective overwrite set, preventing authority escalation and self-lockout. Incomplete, malformed, contradictory, over-capacity, or mismatched evidence fails planning before approval.

The process-keyed HMAC digest binds the normalized request, one-shot operation-key hash, verified identities, guild owner, exact channel and parent, complete overwrite set, complete role inventory, target member or role evidence, effective-access impact, connector authority before and after, parent synchronization, and warnings. Names and the audit reason can be reviewed in the plan, but only bounded identifiers and outcomes enter durable records. A connector restart invalidates the digest. The MCP adapter rebuilds the plan before approval, and the service rebuilds it immediately before mutation.

Execution atomically reserves the operation-key hash and appends a pending content-free activity record before one non-retried PUT or DELETE. It then reads the direct channel again and compares both the exact target and the complete overwrite set with the reviewed prospective state. A full match is completed; valid concurrent change is completed-with-drift; a known pre-write Discord 4xx is failed; transport failure, Discord 5xx, or any post-write failure is uncertain. Every reserved key remains permanently spent, with no automatic retry or compensating write.

Changes to the same channel serialize inside one process and replan after a preceding determinate outcome. The production facade additionally acquires durable exact channel-and-role or channel-and-member claims, so connector processes sharing the activity-state root exclude overlapping permission-overwrite changes. An uncertain result retains those claims for operator review before another key can be reserved. Permission names, bitfields, role or member names, audit reasons, and raw operation keys never enter activity records, operation receipts, diagnostics, or telemetry. See Discord's edit and delete endpoints plus its permissions reference.

Canonical source: docs/reference.md