feat(gateway): optional speaker-name prefix on every stored message

[withzombies]

What does this PR do?

Adds an opt-in knob — gateway.always_name_prefix in config.yaml / env var
HERMES_ALWAYS_NAME_PREFIX — that extends the [Name] sender prefix to
every stored inbound message, not just messages in shared multi-user
sessions.

Today the prefix in GatewayRunner._prepare_inbound_message_text fires only
when is_shared_multi_user_session(source) is True, where it disambiguates
participants. In a DM there is only one human, so the prefix is omitted — but
that makes DM and group transcripts structurally different, and a DM transcript
carries no durable record of who was speaking at all: any per-turn identity
context (channel banners, system-prompt notes) is ephemeral to the current
turn, while the stored message text is what survives in session history,
compaction, and session_search. Operators running one agent across several
1:1 channels (e.g. an assistant deployment fielding DMs from multiple people
on multiple platforms) have no way to keep attribution in history.

With the knob enabled every stored message carries the same
[<display name>] <text> shape already used in shared sessions, reusing the
exact same code path — including neutralize_untrusted_inline_text, so hostile
display names get the identical hardening. Default behavior is byte-identical
to today: env var unset ⇒ only shared multi-user sessions get the prefix.

Related Issue

No existing issue. Duplicate search performed (see checklist notes below);
closest existing work:

• PR fix(gateway): always prefix non-DM messages with sender name #80295 / fix(gateway): always prefix non-DM messages with sender name #80235 — "always prefix non-DM messages with sender name":
  changes the default for group/thread messages under
  group_sessions_per_user=True. This PR is complementary, not a duplicate:
  it is strictly opt-in and also covers DMs (chat_type="dm"), which fix(gateway): always prefix non-DM messages with sender name #80295
  deliberately leaves unprefixed. If fix(gateway): always prefix non-DM messages with sender name #80295 lands, this knob still adds the
  DM case; the guard composes (or) cleanly.
• fix(gateway): keep shared-group sender prefix outermost #67886 (prefix ordering), fix(gateway): skip sender prefix for internal events + NO_REPLY contract in async delegation (#66480) #66507 (skip prefix for internal events),
  Label unnamed shared-session participants #44705 (unnamed participants) — adjacent to the same code path, different
  concerns.

Fixes # (none — feature)

Type of Change

• ✨ New feature (non-breaking change that adds functionality)

Changes Made

• gateway/run.py
  • New module-level helper _always_prefix_speaker() (next to the other
    env readers, after _float_env): reads HERMES_ALWAYS_NAME_PREFIX,
    truthy values 1/true/yes/on (case-insensitive, whitespace
    tolerant). Read live so config reloads/tests take effect without
    re-import.
  • Sender-prefix guard in _prepare_inbound_message_text widened from
    if _is_shared_multi_user and source.user_name: to
    if (_is_shared_multi_user or _always_prefix_speaker()) and source.user_name:.
    The body — including the neutralize_untrusted_inline_text hardening and
    its security comment, and the Slack <@U...> author-mention append — is
    untouched.
  • Config→env bridge: gateway.always_name_prefix bridged to
    HERMES_ALWAYS_NAME_PREFIX, config-authoritative and normalized to
    "1"/"0" (same convention as the neighboring
    gateway.trust_recent_files key; unlike platform_connect_timeout,
    which is intentionally env-wins).
• cli-config.yaml.example — commented gateway: block documenting
  always_name_prefix: false (placed after group_sessions_per_user, the
  related session-identity knob).
• website/docs/reference/environment-variables.md — HERMES_ALWAYS_NAME_PREFIX
  row in the gateway env table (next to HERMES_GATEWAY_BUSY_ACK_ENABLED).
• tests/gateway/test_always_name_prefix.py (new)
  • helper truthiness: default off; 1/true/yes/on (any case) on;
    empty/0/false/no/off/garbage off.
  • runtime, through the real _prepare_inbound_message_text (same harness
    as tests/gateway/test_shared_group_sender_prefix.py): a Telegram DM is
    stored bare with the env unset and as [Alice] hello there with it set;
    a hostile display name with embedded newlines is neutralized on the
    opt-in path; a shared Slack thread keeps its existing
    [Alice | Slack user <@U123>] prefix regardless of the knob.
• tests/gateway/test_config_env_bridge_authority.py
  • HERMES_ALWAYS_NAME_PREFIX added to the subprocess env-key probe list.
  • Two bridge tests per the file's pattern: config true overrides a stale
    .env 0 → "1"; explicit config false overrides a stale .env
1 → "0".

How to Test

1. pytest tests/gateway/test_always_name_prefix.py tests/gateway/test_config_env_bridge_authority.py tests/gateway/test_shared_group_sender_prefix.py -q
   → 31 passed.
2. Default unchanged: run the gateway with the knob unset, DM the bot, and
   inspect the stored session transcript (~/.hermes/sessions/) — the user
   message is stored bare, exactly as before.
3. Opt in: add to ~/.hermes/config.yaml:

   gateway:
     always_name_prefix: true

   restart the gateway, DM the bot again — the stored user message is now
   [<your display name>] <text>, matching the shape group messages already
   have. (Or set HERMES_ALWAYS_NAME_PREFIX=1 in .env; config wins if both
   are set.)
4. Group/thread behavior is unaffected in both states (shared sessions were
   already prefixed).

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(gateway): ...)
• I searched for existing PRs to make sure this isn't a duplicate —
  gh search prs --repo NousResearch/hermes-agent "user name prefix",
  "speaker", "sender prefix", "always name prefix", plus the same
  via gh search issues. Closest matches (fix(gateway): always prefix non-DM messages with sender name #80295/fix(gateway): always prefix non-DM messages with sender name #80235, fix(gateway): keep shared-group sender prefix outermost #67886, fix(gateway): skip sender prefix for internal events + NO_REPLY contract in async delegation (#66480) #66507,
  Label unnamed shared-session participants #44705, issues [Bug] Telegram Group Chat: Agent cannot see sender names / user identity #26581/[Gateway/Telegram] user.id is captured but not included in shared multi-user message prefix #32417/[Feature]: Expose user_id alongside user_name in single-user session context #35147) are adjacent, not duplicates —
  none adds an opt-in prefix for DMs (see Related Issue).
• My PR contains only changes related to this fix/feature (single commit)
• I've run pytest tests/ -q and all tests pass (targeted suites above,
  plus neighbors of the touched guard: tests/gateway/test_session.py,
  test_reply_to_injection.py, test_context_ref_expansion_runtime.py — 65 passed)
• I've added tests for my changes
• I've tested on my platform: macOS 15 (Darwin 25.3.0)

Documentation & Housekeeping

• I've updated relevant documentation (website/docs/reference/environment-variables.md)
• I've updated cli-config.yaml.example (new gateway.always_name_prefix key)
• I've updated CONTRIBUTING.md or AGENTS.md — N/A (no architecture/workflow change)
• I've considered cross-platform impact — N/A (pure env/config read, no platform-specific code)
• I've updated tool descriptions/schemas — N/A (no tool behavior change)

Screenshots / Logs

$ pytest tests/gateway/test_always_name_prefix.py tests/gateway/test_config_env_bridge_authority.py tests/gateway/test_shared_group_sender_prefix.py -q
...............................                                          [100%]
31 passed in 2.19s

$ uvx ruff@0.15.10 check gateway/ tests/
All checks passed!

---

🤖 Generated with Claude Code