[Brandon Werner (brandwe)]

The problem

AGENTS.md requires model-facing Teams and email content to pass through wrap_external, but channel pushes didn't deliver that:

• Teams: read() wrapped the message, then _summarize_content stripped every tag before the push, including the envelope.
• Email: the sender name, subject and body preview were pushed with no wrapping and no sanitizing. Only read_email wrapped anything.

The body prompt's rule against following embedded instructions still applied, but nothing marked this text as data.

The fix

A push can't carry angle brackets, because the host's client has closed the MCP stream on them. So new wrap_for_channel writes the same envelope in a bracket form:

[external_content source="email" sender="someone@contoso.com"]Text from outside[/external_content]

The body can't forge a marker. Character references are decoded first, square brackets become parentheses, the marker's name becomes external content however it's padded or split, and fullwidth brackets are covered. ENTRABOT_XPIA_WRAP_ENABLE=false turns this off too.

Push	Envelope	Why
Teams, from a verified sponsor	No	This is how a sponsor gives an instruction
Teams, from anyone else	Yes	Their message is a request, not a command
Teams, sponsor lookup failed	Yes	Fails closed, and the message is still delivered
Email, from anyone	Yes	A From address can be forged

Decisions to check

A sponsor's Teams message stays unwrapped. The body prompt tells the model to refuse any directive inside an envelope, and says a sponsor must restate it "outside any envelope". Today the sanitizer's stripping is what lets a sponsor's Teams message count as an instruction. Wrapping those too would leave a sponsor no way to instruct the agent. SponsorGate decides, from Graph identity and never a display name. I used the gate rather than the binding path's sponsor records because the gate also knows the ID a federated sponsor has in a chat.

This changes how emailed instructions work. An email showing a sponsor's address now arrives as data, and the body prompt says to confirm in Teams before acting on it.

Other people can still ask for things. The body prompt now says a wrapped message can still ask something, and channel discipline decides whether the agent replies. Nothing in an envelope changes its rules, tools or scope, or authorizes an action.

Delegated sessions have no Agent Identity to ask, so only the signed-in human stays outside the envelope.

Testing

pytest: 2288 passed, 51 skipped, with and without ENTRABOT_KEEP_MEMORY_LOCAL=true. ruff check . is clean.

New tests cover the envelope's shape, forged markers in a dozen forms, hostile senders, every row of the table, the lookup running off the event loop and being cached, a failed lookup retrying only after a wait, and no angle brackets anywhere in a hostile email's params.

Checked against a live tenant, read-only: the real sponsor lookup loads, a same-tenant sponsor's recent messages match it, other people's don't, and the envelope for each of those came out well formed.

Not tested against a live client. I haven't confirmed how the bracket form renders in a real Claude Code session, or how the model responds to it. After merging and restarting the server, someone should check:

• A Teams DM from the sponsor is treated as an instruction.
• A Teams message from someone else shows the envelope and still gets a reply when the agent is @mentioned.
• An email shows the envelope, and the MCP stream stays up when its subject contains <.

Known limits

• If the sponsor lookup fails, a sponsor's Teams push arrives wrapped until a later lookup succeeds, so the agent may ask them to restate an instruction. A failed lookup waits 60 seconds before trying again. This is listed in docs/project/status.md.
• A push trusts a cached sponsor list for 15 minutes, so someone removed as a sponsor can keep speaking outside the envelope for that long.
• The first push from anyone but a verified sponsor can wait on the lookup, which reads the members of every watched chat. It runs in a worker thread, so the event loop isn't blocked, but that poll cycle is.
• fix(storage): keep the watched-chat list and email cursor in the memory backend #142 adds _load_sponsor_gate, which refuses to cache a provisional or stale gate. _sender_is_sponsor should move to it once both are in main, whichever merges second.

🤖 Generated with Claude Code

[Copilot]

🟡 Changes recommended

The gate cache can continue trusting removed sponsors indefinitely, while a cache invalidation race and missing sponsor-email enrichment can incorrectly reject legitimate federated sponsor replies.

3 open issues

• Expire and refresh cached sponsor gates · New
• Use an Agent User token to enrich sponsor emails · New
• Avoid caching stale gates after watched chats change · New

What changed in this PR

This PR adds a channel-safe external-content envelope to Teams and email notifications, preserving the distinction between external data and trusted sponsor instructions.

Changes:

• Adds bracket-form wrapping with body and attribute sanitization.
• Wraps non-sponsor Teams pushes and all email pushes, with cached sponsor lookup and failure backoff.
• Adds regression coverage and updates security guidance and documentation.

File	Description
tests/​test_mcp_server_integration.py	Updates the expected Teams push envelope.
tests/​test_mcp_push_envelope.py	Tests push wrapping, sponsor checks, and lookup failures.
tests/​security/​test_xpia_channel_wrap.py	Tests marker escaping, attributes, and the rollback flag.
tests/​conftest.py	Prevents real sponsor-directory lookups during tests.
src/​entrabot/​security/​xpia.py	Adds the bracket-form channel wrapper.
src/​entrabot/​mcp_server.py	Applies push wrapping and sponsor verification.
prompts/​anatomy/​security.md	Defines how bracket envelopes and sponsor messages are treated.
docs/​reference/​api/​security.md	Documents the wrapper API and its call sites.
docs/​project/​status.md	Records degraded behavior during sponsor-lookup failures.
docs/​architecture/​security-boundaries.md	Explains push trust boundaries and sponsor checks.
docs/​architecture/​messaging-and-delivery.md	Documents envelope handling during delivery.
CHANGELOG.md	Records the channel-envelope fix.
AGENTS.md	Updates external-content guidance for channel pushes.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

Encoded sender delimiters can break out of the external-content envelope after decoding, while HTML-style summarization deletes valid content from plain-text email fields.

2 open issues

• Escape encoded delimiters in email sender attributes · New
• Use an Agent User token to enrich sponsor emails

1 previously missed issue

In code that hasn't changed since last review

Preserve angle-bracket text in plain-text email fields

src/​entrabot/​mcp_server.py:1789

Email sender fields, subjects, and bodyPreview are plain text, but _summarize_content treats text between angle brackets as HTML and deletes it. For example, Deploy <release-123> becomes Deploy, and the preview Alert when CPU < 50% and memory > 90%. becomes Alert when CPU 90%. Use plain-text truncation and delimiter neutralization for these fields (also at lines 1798 and 1815), preserving channel safety when wrapping is disabled.

2 resolved since last review

• Expire and refresh cached sponsor gates
• Avoid caching stale gates after watched chats change

_{Review effort: Balanced}

[Brandon Werner (brandwe)]

Fixed in 44f9361: Copilot's latest review also flagged that plain-text email fields went through the HTML sanitizer, which deleted real words. They now use channel_safe_text, which keeps the words and swaps angle brackets for look-alikes, including when wrapping is switched off.

[Copilot]

🟡 Changes recommended

Deleting forbidden characters can reconstruct character references that, if decoded by the client, let sender content close the security envelope before the untrusted email body.

1 open issue

• Prevent filtered characters from assembling envelope delimiters · New

2 resolved since last review

• Escape encoded delimiters in email sender attributes
• Use an Agent User token to enrich sponsor emails

_{Review effort: Balanced}

[Brandon Werner (brandwe)]

Fixed in 7ae70c1: unsafe characters in an attribute now become spaces instead of being removed, so closing up a gap can't assemble a new reference. The regression tests decode the filtered output repeatedly and check the marker's shape.