What does this PR do?

Adds a normalized gateway channel identity block so agents can reliably distinguish the active channel/thread without relying on platform-specific wording in the source description.

This is intentionally scoped after #17702, which preserves named Matrix room identity. This PR adds a cross-platform normalized identity surface.

Related Issue

Related PR: #17702

No issue found for the narrower channel identity follow-up. Related search terms returned mostly unrelated i18n/gateway items.

Type of Change

• Bug fix
• New feature
• Security fix
• Documentation update
• Tests
• Refactor
• New skill

Security hardening benefit: the prompt explicitly labels channel identity as untrusted transport metadata for routing, not user instructions.

Changes Made

• gateway/session.py: adds compact deterministic SessionContext.channel_identity_json and renders it as JSON in the session context prompt.
• gateway/session.py: honors existing prompt PII redaction by hashing channel/thread/parent IDs when redact_pii=True, and omits channel_name when prompt PII redaction is active.
• gateway/session_context.py / gateway/run.py: exposes HERMES_SESSION_CHANNEL_IDENTITY through the existing contextvar-based session env path.
• tests/gateway/test_channel_identity.py and tests/gateway/test_session_env.py: add regression coverage for prompt identity, redaction/escaping, deterministic JSON, untrusted-metadata wording, and contextvar exposure.

How to Test

RED observed before implementation:

• python -m pytest tests/gateway/test_channel_identity.py tests/gateway/test_session_env.py::test_set_session_env_includes_normalized_channel_identity -q -o 'addopts=' --tb=short
• Result: failed for missing prompt block, missing channel_identity_json, and missing HERMES_SESSION_CHANNEL_IDENTITY.

Targeted tests:

• python -m pytest tests/gateway/test_session.py tests/gateway/test_session_env.py tests/gateway/test_channel_identity.py -q -o 'addopts=' --tb=short → 93 passed
• Latest focused verification: python -m pytest tests/gateway/test_channel_identity.py tests/gateway/test_session_env.py -q -o 'addopts=' → 16 passed

Static/syntax checks:

• python -m py_compile gateway/session.py gateway/session_context.py gateway/run.py tests/gateway/test_channel_identity.py tests/gateway/test_session_env.py
• git diff --check
• Added-line privacy/security scan → clean

Full-suite status:

• Not run in this PR pass; this PR is verified with targeted gateway/session tests above.

Independent review:

• Passed; no security/privacy or logic blockers after prompt wording and redaction handling were tightened.

Security / Platform Notes

• No credential, token, shell/subprocess, filesystem deletion, migration, or network/API behavior changes.
• Prompt channel identity uses sanitized JSON rendering and follows the existing redact_pii prompt redaction gate for raw channel/thread/parent IDs.
• Privacy caveat addressed: display channel names can contain project/customer/person names, so channel_name is omitted from the normalized channel identity block whenever prompt PII redaction is active.
• HERMES_SESSION_CHANNEL_IDENTITY is session-local via contextvars, matching existing gateway session env behavior and avoiding concurrent-message cross-talk.
• Test fixtures use sanitized IDs only (example.org, channel-123, thread-456, parent-789).

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this feature
• I ran the targeted gateway/session tests listed above.
• I ran pytest tests/ -q.
• I've added tests for my changes
• I've tested on my platform: Linux / targeted gateway tests

Documentation & Housekeeping

• Documentation update needed
• No config keys changed
• Cross-platform impact considered: contextvars/JSON stdlib only
• Tool descriptions/schemas unchanged

Review feedback remediation (2026-04-30)

• Cleaned up the PR type checklist so it no longer claims docs/refactor/new-skill/security-fix scope.
• Cleaned up the full-suite wording: targeted tests are reported in the test plan/checklist; pytest tests/ -q is explicitly not claimed.
• Confirmed the channel identity prompt labels the JSON as untrusted transport metadata for routing, not user instructions.
• Confirmed channel identity JSON is compact and deterministic with sorted keys.
• Confirmed redact_pii=True hashes stable channel/thread/parent IDs and omits human-readable channel_name.
• Added regression coverage showing malicious/newline-containing channel names remain escaped JSON data and do not become prompt structure.

Relationship to adjacent PRs

Builds on the room-identity behavior fixed in #17702 and adds the generic gateway/session layer: normalized channel identity is rendered in session context and exposed through session contextvars.

This PR does NOT resolve project/repo bindings and does NOT block tools. #17938 is the enforcement layer.