#10925·zeroclaw

[Feature]: Support input-driven mirror voice replies on Matrix

Author: Audacity88Created Sep 17, 2026Updated Sep 17, 2026
Labelsenhancementchannelchannel:corechannel:matrixpriority:p2status:acceptedfollow-uprisk:medium

Summary

Support input-driven spoken replies for Matrix peer groups using output_modality = "mirror".

Problem statement

Matrix supports configured voice replies after #10489, but its documentation explicitly says that mirror is unimplemented and returns text. A user who sends a voice message cannot receive a spoken reply in kind without selecting voice, which also voices replies to text messages. This request covers the deferred mirror feature, not a defect in the accepted scope of #10489 or a reopening of #10488.

Proposed solution

For a Matrix reply governed by a mirror peer group, preserve the originating message's modality through dispatch to the reply decision. With TTS configured, a voice input should receive a voice note alongside the normal text reply; a text input should receive text only. Use actual inbound voice-message metadata, not transcript prefixes or reply-text heuristics.

Keep suppress_voice authoritative and retain existing explicit force_voice behavior. Messages without an originating input, including proactive deliveries, should not acquire a guessed mirror modality. Preserve threading, encrypted attachment delivery, canonical agent ownership, and the existing text fallback when synthesis is unavailable or fails.

Non-goals / out of scope

No changes to other channels, transcription setup, voice-only delivery, room-wide last-message modality tracking, or proactive-message modality policy. No new TTS provider or configuration schema is requested.

Alternatives considered

  • Keep the documented text-only mirror behavior: avoids a behavior change but leaves voice-in/text-out as the only default Matrix behavior.
  • Select voice: available today, but voices replies to text input too.
  • Infer from the last voice message in a room: can mix users or concurrent turns; prefer origin-bound metadata.

Acceptance criteria

  • In a mirror group with TTS configured, a voice-origin conversational reply delivers text plus a voice note in the correct thread.
  • A text-origin reply remains text-only unless explicit message intent requests voice.
  • Suppression prevents synthesis even for voice-origin replies.
  • Concurrent users and threads cannot leak modality into each other's replies.
  • Proactive messages with no origin retain existing behavior; mirror alone does not trigger voice.
  • Existing encrypted audio delivery and text fallback remain intact.
  • Update Matrix documentation and provide focused tests of modality propagation and sender decisions.

Architecture impact

Matrix inbound message metadata, channel dispatch, and outbound modality selection. Identify and reuse the canonical per-message modality representation rather than introducing room-global state or duplicate policy.

Risk and rollback

Enabling this changes existing mirror groups from text-only to text-plus-voice after voice input. Since mirror is the default, document the rollout and operator impact before implementation; TTS remains a prerequisite. Operators can select text to retain text-only replies. Reverting the implementation restores the documented unsupported-mirror behavior.

Expected routing

Could become contributor-ready after maintainer scoping

Next decision surface

Use this issue to confirm origin-metadata propagation and rollout of the changed default behavior before implementation. Related completed work: #10489 and #10488.

Breaking change?

Yes — behavioral change for existing Matrix mirror groups with TTS configured; no schema change is requested.

Data hygiene checks

  • I removed personal/sensitive data from examples, payloads, and logs.
  • I used neutral, project-focused wording and placeholders.