Summary

This is PR 4 in the Matrix gateway parity series and should be reviewed after
#18505, #18506, and #18507.

It adds optional support for structured Matrix agent metadata emitted by the
companion Synapse module
AgentFirstModule.

The integration is intentionally optional. Standard Matrix homeservers do not
emit this metadata, and the Matrix adapter falls back to existing behavior when
the fields are absent.

Why

The first three Matrix PRs add the foundation, native Matrix tools/interactions,
and Matrix rendering/media/E2EE/diagnostics hardening.

This PR adds the optional enhancement layer for deployments that want richer
agent-native Matrix behavior from their homeserver:

• structured session scope hints
• room identity hints
• tool status metadata
• approval request metadata
• tool call/result metadata
• typing/status metadata

Changes

Matrix adapter

• Parses optional AgentFirstModule metadata from Matrix event unsigned.
• Exposes parsed metadata on inbound MessageEvent.agent.
• Applies safe room/session metadata to SessionSource.
• Keeps behavior unchanged when metadata is missing.

Session context

• Adds optional SessionSource.agent_metadata.
• Adds SessionSource.apply_agent_metadata().
• Applies session_scope=room by clearing synthetic thread scope for the turn.
• Applies room_identity only when the metadata room ID matches the actual Matrix room ID.
• Adds a concise Matrix prompt note when AgentFirstModule metadata is present.

Agent UI helpers

• Adds gateway/agent_ui.py with small rendering helpers for approval request and tool status payloads.
• No new dependencies.

Docs/tests

• Documents optional AgentFirstModule metadata support in the Matrix guide.
• Adds focused tests for parsing, inbound handler propagation, room identity safety, session key behavior, prompt notes, UI helpers, and unchanged behavior when AgentFirst metadata is absent.

Security / Compatibility

• No behavior change on standard Matrix homeservers.
• Durable routing still uses Matrix room IDs, not mutable room names.
• AgentFirst room identity metadata cannot override the event's actual Matrix room ID.
• No Honcho or memory-provider behavior is changed.
• No new dependencies are introduced.

Validation

Passed locally:

python -m py_compile \
  gateway/platforms/matrix.py \
  gateway/session.py \
  gateway/platforms/base.py \
  gateway/agent_ui.py

scripts/run_tests.sh \
  tests/gateway/test_matrix_agentfirst_metadata.py \
  tests/gateway/test_matrix.py \
  tests/gateway/test_matrix_project_context_isolation.py \
  tests/gateway/test_matrix_exec_approval.py \
  tests/tools/test_matrix_tools.py \
  -q -o 'addopts='

git diff --check

Result:

259 passed

Stack

Builds on:

• fix(matrix): isolate room context and restore reliable inbound dispatch #18505
• feat(matrix): add scoped native tools and reaction controls #18506
• feat(matrix): harden rendering, media, E2EE and diagnostics #18507

This PR should be reviewed after the first three Matrix PRs.