Reviewed exact voice-channel status changes

Voice-channel status is ephemeral state that Discord omits from the ordinary Channel REST object. The connector handles it as a stricter extension of the existing channel-metadata boundary: set capabilities.channelMetadataChanges: true, list every eligible exact channel in scopes.channelMetadataIds, and keep that list inside readScope.channelIds when an ordinary read allowlist exists. No additional configuration field or environment variable exists. GUILD_VOICE is the only accepted type; Stage, thread, direct-message, directory, and future channel types fail before the broad Gateway query.

get_voice_channel_status and discord://guilds/{guildId}/channels/{channelId}/voice-status accept one exact guild and channel pair. The service first performs an exact HTTP metadata read to prove type, ownership, and local scope. It then uses a projection-only Gateway connection with the nonprivileged GUILDS intent to send opcode 43 for that guild with only fields: ["status"]. Requests serialize per guild because Discord supplies no correlation nonce. The parser bounds and validates the complete CHANNEL_INFO response, selects the exact target, and discards every non-target status and channel ID before building the result. Only response counts, count-only unknown fields, Gateway sequence, timestamps, and whether the target value was omitted, null, or present accompany the transient untrusted target text. The result is private, uncached, unjournaled, and never enters the generic event feed.

Every read and plan verifies pinned application and bot identity, exact guild ownership, connector membership, a complete bounded role inventory, strict channel overwrites, and the connector's current voice state through Discord's exact current-user route. A documented unknown-voice-state response is explicit disconnected evidence. The projection reveals only target, other, or disconnected, never another channel ID. Complete authority requires effective VIEW_CHANNEL plus SET_VOICE_CHANNEL_STATUS; when the connector is not connected to the exact target, the plan also requires MANAGE_CHANNELS. Guild owner and ADMINISTRATOR bypass semantics are recognized only from complete evidence and are not the recommended deployment.

plan_voice_channel_status_change requires exact guild and channel IDs, explicit null to clear or trimmed nonblank valid-Unicode text of at most 500 code points without control characters, one bounded Discord audit-log reason, and a unique one-shot operation key. Omitted status, empty text, fuzzy lookup, names as targets, and unknown fields fail before planning. The process-keyed digest binds verified identity, strict metadata, current Gateway representation, desired status, Gateway evidence counts, complete roles and overwrites, connection class, conditional permissions, audit reason, and domain-separated operation-key hash. A matching current and desired value is already-current and requires no confirmation, durable claim, reservation, activity record, REST request, or settling wait.

execute_voice_channel_status_change rebuilds the plan before signed MCP elicitation, requires host write approval and explicit interactive confirmation, and rebuilds it again inside durable exact-channel and guild channel-collection coordination. A real change atomically reserves the one-shot key, appends pending content-free activity, subscribes to the exact target's transient update before dispatch, and sends one non-retried PUT with only { "status": value } plus the encoded audit reason. After Discord returns no content, the update receives a short bounded settling window, but the service always sends a new opcode-43 query as the authoritative readback. A match completes, a valid different value completes with drift, a known Discord 4xx refusal fails, and an ambiguous transport, server, response, Gateway-continuity, or final-readback outcome is uncertain and potentially completed. Every reserved key remains spent; uncertainty quarantines the exact channel without retry, rollback, compensation, or a fresh key.

Status text, status hashes, channel and guild names, role names, audit reasons, raw operation keys, other connection channel IDs, raw Gateway payloads, non-target values, and settling-event values never enter activity records, operation receipts, coordination claims, diagnostics, logs, metrics, traces, or caches. Durable records retain only bounded exact identifiers, operation kind, plan digest, operation-key hash, timestamps, fixed outcomes, verification, and sanitized error categories. The workflow does not expose occupant enumeration, status history, presence changes, bulk actions, Stage moderation, retry, rollback, or reconciliation.

Canonical source: docs/reference.md