May 7, 2026 Update

This PR has been refreshed on top of the updated Matrix foundation branch after the v2026.5.7 release.

Branch Refresh

• Rebased onto refreshed PR 1 / feature/matrix-foundation.
• Current head: a75c78d78.
• Base head observed during refresh: 04193cf71.

Matrix UX Fix

• Increased Matrix tool-progress preview length from the inherited compact default to a Matrix-specific default of 160 characters.
• Rationale: Matrix uses editable progress panes, so slightly longer bounded previews are useful and do not create the same channel noise as permanent one-message-per-tool platforms.
• The value remains bounded and can still be overridden through display.platforms.matrix.tool_preview_length.

Local Validation

Passed:

scripts/run_tests.sh \
  tests/tools/test_matrix_tools.py \
  tests/gateway/test_matrix_exec_approval.py \
  tests/gateway/test_matrix_mention.py \
  tests/gateway/test_matrix_project_context_isolation.py \
  tests/agent/test_prompt_builder.py::TestPromptBuilderConstants::test_platform_hints_matrix \
  -q -o 'addopts='

Additional Matrix/display validation passed as part of the final stack check:

338 passed, 1 skipped

Also passed:

python -m py_compile \
  gateway/platforms/matrix.py \
  gateway/run.py \
  tools/matrix_tools.py \
  toolsets.py \
  gateway/display_config.py

git diff --check

Update: Matrix output defaults

This PR now defaults Matrix chat output to final answers only.

Why:

• Matrix clients often treat edited/replaced progress messages as read-marker-relevant events.
• Live tool/thinking panes can cause clients to jump around the room after returning to the channel.
• Global gateway streaming/progress settings should not accidentally enable that behavior for Matrix.

Behavior after this update:

• Matrix suppresses live tool/thinking progress and interim assistant streaming by default.
• Final responses are still delivered normally.
• Operators can explicitly opt back in with:

display:
  platforms:
    matrix:
      tool_progress: new
      streaming: true
      interim_assistant_messages: true

Validation:

• Focused Matrix/gateway test set passes locally: 297 passed.

History cleanup

Rebased and cleaned commit history for reviewability.

• No scope change.
• Final tree is equivalent to the previous branch state.
• Focused Matrix validation still passes locally: 297 passed.

Update: Matrix tool activity output

Adjusted the Matrix output defaults after local client testing.

Behavior now:

• Matrix shows live tool activity by default (tool_progress: new).
• Matrix still suppresses raw reasoning/thinking panes unless display.platforms.matrix.show_reasoning: true is explicitly set.
• Matrix response token streaming remains off unless display.platforms.matrix.streaming: true is set.
• Tool activity is sent with a Matrix formatted-body details/summary block plus a plain-text fallback body, so clients that support collapsible HTML can hide/show details while other clients still show usable text.

Validation:

• Focused Matrix stack passed locally: 323 passed.
• py_compile and git diff --check passed.

v2026.5.16 refresh

Rebased this Matrix PR stack onto current upstream main after the v2026.5.16 / v0.14.0 release.

Notes:

• The v2026.5.16 release did not include this Matrix parity work; these PRs remain open and unmerged.
• Checked Matrix/gateway-adjacent upstream changes from the release window.
• Focused Matrix validation passed locally: 323 passed.
• py_compile and git diff --check passed.

Draft stacked preview

This PR is intentionally marked draft while #18505 is the active review target. It is kept open so maintainers and external reviewers can see the next Matrix layer without treating it as an independent merge candidate yet.

Depends on

• fix(matrix): isolate room context and restore reliable inbound dispatch #18505 for Matrix room/session isolation and reliable inbound dispatch.

Scope

• Matrix-native tools and Matrix toolset registration.
• Current-room authorization for Matrix tools.
• Explicit admin gates for redaction, invites, and room creation.
• Reaction-based dangerous-command approvals and /model selection.
• Collapsible Matrix tool-activity messages with raw thinking hidden by default.

Design note
Matrix does not provide a portable native button surface equivalent to Slack Block Kit, Discord components, or Telegram inline keyboards. This PR keeps the upstream-safe path reaction-based so it works on ordinary Matrix homeservers and clients. Optional richer metadata remains isolated in #23815.

I will move this out of draft once #18505 has maintainer direction.

Update: Matrix tool activity preview width

Pushed a focused fix for Matrix tool-activity rendering.

What changed

• Matrix default tool_preview_length is now 1000 instead of 320.
• Matrix no longer falls back to the generic 40-character chat preview cap when global display.tool_preview_length: 0 is present.
• Added regression coverage proving Matrix tool activity preserves long command previews in the collapsible <details><pre><code> block.

This keeps the single edited tool-activity pane readable without enabling raw thinking or response streaming. The downstream stacked branches (#18507 and #23815) have the same fix.

Correction: restored Matrix tool activity preview scope

I backed out the broader preview-width change from the previous update.

Current state

• Matrix tool_preview_length is back to 320.
• The extra gateway/run.py fallback logic was removed.
• The wider 1000 default and its regression test were removed.

This keeps the PR closer to the existing display configuration model and avoids expanding the review surface. For deployments that see short Matrix tool lines because global display.tool_preview_length: 0 is present, the intended configuration is an explicit Matrix platform override:

display:
  platforms:
    matrix:
      tool_progress: new
      tool_preview_length: 320

The local all-stack test branch has the same rollback.

Rebased this PR onto current main (56236b16e) after the v0.16.0 / v2026.6.5 release.

Notes:

• Preserved upstream Matrix !command alias behavior.
• Kept the current lazy dependency / Markdown dependency model from main.
• Fixed Matrix test isolation around mautrix stubs and lazy-dependency requirements.
• CI is green after the rebase.
• This PR remains stacked on fix(matrix): isolate room context and restore reliable inbound dispatch #18505.

The custom Synapse/AgentFirst metadata PR (#23815) has been retired from the active stack to keep this series focused on upstreamable core Matrix functionality.

Jun 10, 2026 stacked preview refresh

Rebased onto current upstream main via the refreshed foundation stack (#18505).

Incremental scope (review commits after #18505 branch point)

• tools/matrix_tools.py — room-local Matrix-native tools with layered authorization:
  • session-platform gate (Matrix-only at runtime)
  • current-room default; MATRIX_TOOLS_ALLOW_CROSS_ROOM / _DESTRUCTIVE opt-ins
  • per-action admin gates for redaction, invites, room creation
  • MATRIX_ALLOWED_ROOMS allowlist
• Reaction-based dangerous-command approval + requester-bound validation
• Reaction-based /model picker
• Thinking + tool-activity progress panes (gateway/run.py)
• i18n catalog parity for Matrix slash-command keys (cherry-picked from foundation)

Local validation

.venv/bin/python -m pytest \
  tests/tools/test_matrix_tools.py \
  tests/gateway/test_matrix_exec_approval.py \
  tests/gateway/test_matrix_mention.py \
  tests/gateway/test_run_progress_topics.py \
  tests/gateway/test_matrix_project_context_isolation.py -q

Result: passes locally on refreshed branch (part of 529-test Matrix suite run today)

Review note

Until #18505 merges, the Files changed tab includes foundation commits. For incremental review, filter to the 11 commits after the foundation branch point (from 7424b0aa4 feat(matrix): add scoped native tools and reactions through f9fc0705a).

Leaving this as draft per prior agreement — will mark ready for review once maintainers signal on #18505.

Jun 11 stacked refresh

Restacked this PR onto the updated #18505 foundation branch.

• The incremental range now contains only the 10 Matrix tools/interactions commits for this PR.
• Duplicated foundation fixes were removed from this branch history.
• No independent scope change here beyond inheriting the fix(matrix): isolate room context and restore reliable inbound dispatch #18505 review fixes.

Validation:

• GitHub CI is green on this PR.

Jun 11 update: #18505 merged, branch rebuilt on main

#18505 has landed in main, so this PR has been rebuilt on top of the merged foundation commit.

• Commit list now contains only this PR's 10 Matrix tools/interactions commits.
• Old foundation commits from the previous 3-PR stack are no longer part of this PR.
• feature/matrix-full-stack in the fork was refreshed to the cleaned top of stack.
• This PR is now marked ready for review as the next active Matrix layer.

Validation:

• Local Matrix/browser subset: 375 passed, 1 skipped.
• GitHub CI is green.