Skip to content

Open-source AI teammates in Slack, Teams, Discord, Telegram and Mattermost. Self-host it, with any agent harness and any model.

Fix Switch Trust guardrails: remove private hoot links, fix alert/error notices

Timo Bozsolik-Torresff17d1f00980
diff --git a/core/switch_core/bridges/agent/protocol/agent_core.py b/core/switch_core/bridges/agent/protocol/agent_core.py
index 8b83ef216..0e7b32a5b 100644
--- a/core/switch_core/bridges/agent/protocol/agent_core.py
+++ b/core/switch_core/bridges/agent/protocol/agent_core.py
@@ -122,6 +122,7 @@ from switch_core.trust.client import (
GuardrailBlockedError,
NullTrustClient,
TrustClient,
+ TrustOutcome,
check_message,
trust_annotation,
)
@@ -1211,10 +1212,15 @@ class AgentCore:
content: str,
thread_root_id: str | None,
client: AgentActor,
- ) -> str:
+ ) -> tuple[str, tuple[str, TrustOutcome] | None]:
"""Check agent-authored content against Switch Trust before it is
- sent. Returns the content to actually send — unchanged, redacted, or
- carrying a short non-blocking annotation. Raises
+ sent. Returns the content to actually send — unchanged or redacted —
+ and, on an ALERTED/ERRORED verdict, an (annotation, outcome) pair for
+ the caller to post as a notice once the real content has actually been
+ sent (`_post_trust_alert_notice`, threaded under that send's own
+ event_id rather than under this call's pre-send `thread_root_id`, so
+ the notice reads as a reply to the flagged message, not to whatever
+ thread the agent happened to be posting in). Raises
`GuardrailBlockedError` on a BLOCKED verdict, or on a REDACTED verdict
Switch Trust gave us nothing to redact with — sending the original
content then would be indistinguishable from not checking at all —
@@ -1234,9 +1240,8 @@ class AgentCore:
if check.redacted_content is not None:
content = check.redacted_content
annotation = trust_annotation(check)
- if annotation is not None:
- content = f"{content}\n\n{annotation}"
- return content
+ pending_alert = (annotation, check.outcome) if annotation is not None else None
+ return content, pending_alert
async def _post_trust_blocked_notice(
self, room: RoomDescriptor, thread_root_id: str | None, client: AgentActor
@@ -1267,6 +1272,48 @@ class AgentCore:
exc_info=True,
)
+ async def _post_trust_alert_notice(
+ self,
+ room: RoomDescriptor,
+ reply_to_event_id: str,
+ annotation: str,
+ outcome: TrustOutcome,
+ ) -> None:
+ """Tell the room a response was flagged (or could not be fully
+ checked), as its own notice threaded under the flagged reply's own
+ event id — not the pre-send thread the agent happened to be posting
+ in — rather than appended to the reply itself. Mirrors how
+ `CollaborationCore._post_trust_notice` threads an ALERTED/ERRORED
+ human-authored message under the message that triggered it."""
+ admin = next(
+ (
+ c
+ for c in self.client_lifecycle.get_by_type("admin", require_tenant_id())
+ if isinstance(c, SystemActor)
+ ),
+ None,
+ )
+ if admin is None:
+ return
+ message_type = (
+ AdminMessageType.TRUST_ALERTED
+ if outcome == "alerted"
+ else AdminMessageType.TRUST_ERRORED
+ )
+ try:
+ await admin.send_admin(
+ room.transport_room_id,
+ annotation,
+ message_type=message_type,
+ thread_root_id=reply_to_event_id,
+ )
+ except Exception:
+ logger.warning(
+ "Could not post a Switch Trust alert notice in %s",
+ room.id,
+ exc_info=True,
+ )
+
async def _post_role_change_notice(
self, agent_id: str, transport_room_id: str, action: str
) -> None:
@@ -1328,7 +1375,9 @@ class AgentCore:
thread_root_id = await self._resolve_thread_root(
client, room.transport_room_id, thread_id
)
- content = await self._enforce_trust(room, content, thread_root_id, client)
+ content, pending_alert = await self._enforce_trust(
+ room, content, thread_root_id, client
+ )
event_id = await client.send_message(
room.transport_room_id,
content,
@@ -1343,6 +1392,9 @@ class AgentCore:
event_id,
room.transport_room_id,
)
+ if pending_alert is not None:
+ annotation, outcome = pending_alert
+ await self._post_trust_alert_notice(room, event_id, annotation, outcome)
# The agent has replied, so clear any typing indicator raised when the
# inbound message arrived. The message itself is already delivered, so a
# failure here is degraded-but-functional, not a reason to fail the send.
@@ -1797,10 +1849,13 @@ class AgentCore:
client = self.client_lifecycle.get_by_agent_id(agent_id)
if client is None:
raise ValueError("Agent client not running")
- detail = await self._enforce_trust(room, detail, None, client)
- await client.send_message(
+ detail, pending_alert = await self._enforce_trust(room, detail, None, client)
+ event_id = await client.send_message(
room.transport_room_id, f"*{detail}*", format="markdown", metered=True
)
+ if pending_alert is not None and event_id is not None:
+ annotation, outcome = pending_alert
+ await self._post_trust_alert_notice(room, event_id, annotation, outcome)
async def set_runtime_state(
self,
@@ -2526,7 +2581,9 @@ class AgentCore:
client = self.client_lifecycle.get_by_agent_id(agent_id)
if client and client.transport:
- outcome = await self._enforce_trust(room, outcome, None, client)
+ outcome, pending_alert = await self._enforce_trust(
+ room, outcome, None, client
+ )
await client.send_event(
room.transport_room_id,
"com.switch.task.finalise",
@@ -2537,9 +2594,14 @@ class AgentCore:
"outcome": outcome,
},
)
- await client.send_message(
+ event_id = await client.send_message(
room.transport_room_id, outcome, format="markdown", metered=True
)
+ if pending_alert is not None and event_id is not None:
+ annotation, trust_outcome = pending_alert
+ await self._post_trust_alert_notice(
+ room, event_id, annotation, trust_outcome
+ )
async def cancel_task(self, agent_id: str, task_id: str, reason: str) -> None:
"""Cancel a task (requester only)."""
diff --git a/core/switch_core/bridges/collaboration/collaboration_core.py b/core/switch_core/bridges/collaboration/collaboration_core.py
index 13fe69aa5..d1b5445e2 100644
--- a/core/switch_core/bridges/collaboration/collaboration_core.py
+++ b/core/switch_core/bridges/collaboration/collaboration_core.py
@@ -991,6 +991,16 @@ class CollaborationCore:
annotation = trust_annotation(check)
if annotation is not None:
content = f"{content}\n\n{annotation}"
+ # The room itself never relays a human-authored event back out
+ # to a platform (see handle_outbound_message's human-sender
+ # skip), so without this the sender would never see the
+ # annotation their own client just appended to their message.
+ notice_type = (
+ AdminMessageType.TRUST_ALERTED
+ if check.outcome == "alerted"
+ else AdminMessageType.TRUST_ERRORED
+ )
+ await self._post_trust_notice(msg, annotation, notice_type)
event_id = await human_actor.send_message(
transport_room_id,
content,
@@ -1068,9 +1078,10 @@ class CollaborationCore:
async def _post_trust_notice(
self, msg: InboundMessage, body: str, message_type: AdminMessageType
) -> None:
- """Tell the sender's platform a message was blocked or redacted.
- Never lets a failed notice take the inbound message down with it —
- mirrors `AgentCore._post_trust_blocked_notice`."""
+ """Tell the sender's platform what Switch Trust did with their message
+ — blocked, redacted, alerted, or errored. Never lets a failed notice
+ take the inbound message down with it — mirrors
+ `AgentCore._post_trust_blocked_notice`."""
try:
await self._adapter.admin_message(
msg.channel_id,
diff --git a/core/switch_core/clients/admin_messages.py b/core/switch_core/clients/admin_messages.py
index 34ba85d61..125ea3736 100644
--- a/core/switch_core/clients/admin_messages.py
+++ b/core/switch_core/clients/admin_messages.py
@@ -108,6 +108,8 @@ class AdminMessageType(StrEnum):
RUN_NOTICE = "run_notice"
TRUST_BLOCKED = "trust_blocked"
TRUST_REDACTED = "trust_redacted"
+ TRUST_ALERTED = "trust_alerted"
+ TRUST_ERRORED = "trust_errored"
def admin_extra_content(message_type: AdminMessageType | None) -> dict[str, object]:
diff --git a/core/switch_core/trust/client.py b/core/switch_core/trust/client.py
index 70ec0d344..4af8e3f9c 100644
--- a/core/switch_core/trust/client.py
+++ b/core/switch_core/trust/client.py
@@ -1,12 +1,11 @@
"""Switch Trust: a guardrails service checked before a message is sent.
-Calls the check-only endpoint added in
-https://github.com/sandbox-quantum/hoot/pull/2397 — a provider-agnostic
-`messages` array in, a block/allow verdict out, no LLM provider in the loop.
-`NullTrustClient` is what runs when the feature is off (`SwitchConfig.
-trust_enabled` is False): a client that always allows, so no call site has to
-ask whether the feature is on — the same shape as `telemetry/sink.py`'s
-`NullSink`.
+Calls the guardrails external processor's check-only endpoint — a
+provider-agnostic `messages` array in, a block/allow verdict out, no LLM
+provider in the loop. `NullTrustClient` is what runs when the feature is off
+(`SwitchConfig.trust_enabled` is False): a client that always allows, so no
+call site has to ask whether the feature is on — the same shape as
+`telemetry/sink.py`'s `NullSink`.
"""
from __future__ import annotations
@@ -44,7 +43,7 @@ _AGENT_NAME = "Switch Rooms Agents"
# confirmed for OK and BLOCKED in the endpoint's README; REDACTED/ALERTED/
# ERRORED are inferred from the same naming and the documented severity order
# (Blocked > Redacted > Alerted > Errored > OK) — worth confirming once
-# sandbox-quantum/hoot#2397 lands.
+# the external processor's REDACTED/ALERTED/ERRORED outcomes ship.
TrustOutcome = Literal["ok", "blocked", "redacted", "alerted", "errored"]
_OUTCOME_BY_WIRE_VALUE: dict[str, TrustOutcome] = {
@@ -296,7 +295,7 @@ def trust_annotation(result: TrustCheckResult) -> str | None:
if result.outcome == "alerted":
categories = ", ".join(sorted({f.category for f in result.findings}))
detail = categories or "policy alert"
- return f"⚠️ _Switch Trust: {detail} (not blocked)_"
+ return f"⚠️ _Switch Trust flagged this message (not blocked - {detail})._"
if result.outcome == "errored":
return "⚠️ _Switch Trust could not fully check this message_"
return None
diff --git a/core/tests/integration/test_switch_trust_agent_e2e.py b/core/tests/integration/test_switch_trust_agent_e2e.py
index cd0b0d7d9..4bf3d746d 100644
--- a/core/tests/integration/test_switch_trust_agent_e2e.py
+++ b/core/tests/integration/test_switch_trust_agent_e2e.py
@@ -2,9 +2,10 @@
over the real transport (docs/design/switch-trust-guardrails-v1.md).
Drives the genuine path: `AgentCore.send_message` → `_enforce_trust` →
-(blocked: `SystemActor.send_admin` / allowed-or-degraded: the real send) — and
-reads the outcome back out of the `messages` table, so nothing is inferred
-from in-process state.
+(blocked: `SystemActor.send_admin` in place of the reply / alerted or errored:
+the real send plus a separate `SystemActor.send_admin` notice / allowed: the
+real send alone) — and reads the outcome back out of the `messages` table, so
+nothing is inferred from in-process state.
"""
from __future__ import annotations
@@ -234,18 +235,56 @@ async def test_redacted_agent_message_is_sent_with_content_swapped(
assert not any("[email protected]" in row.content.get("body", "") for row in rows)
-async def test_trust_check_failure_fails_open_and_annotates_instead_of_blocking(
+async def test_alerted_agent_message_is_sent_with_a_separate_notice(
harness: Harness, session_env: SessionEnv
) -> None:
agent_id, room_id = await _setup_room(
- harness, session_env, "e2e-trust-failopen", with_admin=False
+ harness, session_env, "e2e-trust-alerted", with_admin=True
+ )
+ harness.protocol.trust_client = _FixedTrustClient(
+ TrustCheckResult(
+ outcome="alerted",
+ policy_id="policy-1",
+ policy_name="default",
+ findings=(
+ TrustFinding(
+ category="pii/email", detector_name="email", severity="low"
+ ),
+ ),
+ )
+ )
+
+ await harness.protocol.send_message(
+ agent_id, room_id, "my email is [email protected]"
+ )
+
+ rows = await _timeline_messages(harness, session_env, room_id)
+ sent = [row for row in rows if row.content.get("body") == "my email is [email protected]"]
+ assert len(sent) == 1
+ admin_rows = [row for row in rows if "com.switch.admin" in row.content]
+ assert len(admin_rows) == 1
+ assert admin_rows[0].content["com.switch.admin"]["type"] == "trust_alerted"
+ assert "Switch Trust flagged this message" in admin_rows[0].content["body"]
+ # Threaded under the flagged reply itself, not under whatever thread (if
+ # any) the agent happened to be posting in.
+ assert admin_rows[0].thread_root_event_id == sent[0].transport_event_id
+
+
+async def test_trust_check_failure_fails_open_and_notifies_instead_of_blocking(
+ harness: Harness, session_env: SessionEnv
+) -> None:
+ agent_id, room_id = await _setup_room(
+ harness, session_env, "e2e-trust-failopen", with_admin=True
)
harness.protocol.trust_client = _FailingTrustClient()
await harness.protocol.send_message(agent_id, room_id, "hello there")
rows = await _timeline_messages(harness, session_env, room_id)
- sent = [row for row in rows if "hello there" in row.content.get("body", "")]
+ sent = [row for row in rows if row.content.get("body") == "hello there"]
assert len(sent) == 1
- assert "Switch Trust could not fully check" in sent[0].content["body"]
- assert not any("com.switch.admin" in row.content for row in rows)
+ admin_rows = [row for row in rows if "com.switch.admin" in row.content]
+ assert len(admin_rows) == 1
+ assert admin_rows[0].content["com.switch.admin"]["type"] == "trust_errored"
+ assert "Switch Trust could not fully check" in admin_rows[0].content["body"]
+ assert admin_rows[0].thread_root_event_id == sent[0].transport_event_id
diff --git a/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_trust.py b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_trust.py
index 07c18980f..a5a605d59 100644
--- a/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_trust.py
+++ b/core/tests/switch_core/bridges/collaboration/test_bridge_inbound_trust.py
@@ -244,6 +244,37 @@ async def test_allowed_message_is_relayed_unaffected() -> None:
assert trust_client.room_ids == ["room-uuid"]
+async def test_alerted_message_reaches_the_room_and_sender_is_notified() -> None:
+ human_actor = _FakeHumanActor()
+ adapter = _FakeAdapter()
+ result = TrustCheckResult(
+ outcome="alerted",
+ policy_id="policy-1",
+ policy_name="default",
+ findings=(
+ TrustFinding(category="pii/email", detector_name="email", severity="low"),
+ ),
+ )
+ bridge = _bridge(human_actor, adapter, _FixedTrustClient(result))
+
+ await CollaborationCore._handle_inbound_message(
+ bridge, _message("my email is [email protected]")
+ )
+
+ assert len(human_actor.sent) == 1
+ _, content = human_actor.sent[0]
+ assert content.startswith("my email is [email protected]")
+ assert "Switch Trust flagged this message" in content
+ # The room content doesn't relay back to the sender's platform, so the
+ # annotation needs its own notice there too.
+ assert len(adapter.admin_messages) == 1
+ channel_id, body, root_or_ref, message_type = adapter.admin_messages[0]
+ assert channel_id == "chan-1"
+ assert "Switch Trust flagged this message" in body
+ assert root_or_ref == "mm-post-1"
+ assert message_type == AdminMessageType.TRUST_ALERTED.value
+
+
async def test_trust_check_failure_fails_open_and_annotates_instead_of_blocking() -> (
None
):
@@ -257,5 +288,9 @@ async def test_trust_check_failure_fails_open_and_annotates_instead_of_blocking(
_, content = human_actor.sent[0]
assert content.startswith("hello there")
assert "Switch Trust could not fully check" in content
- # A degraded check is disclosed inline, not via a separate notice.
- assert adapter.admin_messages == []
+ # Same as an alert: the room content alone never reaches the sender's
+ # platform, so the degraded-check notice needs its own call too.
+ assert len(adapter.admin_messages) == 1
+ _, body, _, message_type = adapter.admin_messages[0]
+ assert "Switch Trust could not fully check" in body
+ assert message_type == AdminMessageType.TRUST_ERRORED.value
diff --git a/docs/design/switch-trust-guardrails-v1.md b/docs/design/switch-trust-guardrails-v1.md
index 01f435201..98c7f8f38 100644
--- a/docs/design/switch-trust-guardrails-v1.md
+++ b/docs/design/switch-trust-guardrails-v1.md
@@ -2,12 +2,10 @@
Integrates Switch with **Switch Trust**, a guardrails service that evaluates a
message against a policy and returns a block/allow verdict. The service
-exposes a `/guardrails/check` endpoint (see
-[hoot#2397](https://github.com/sandbox-quantum/hoot/pull/2397) and its
-[README](https://github.com/sandbox-quantum/hoot/blob/300cece9ec3625a5327a06aea66681c444c53139/services/aispm/guardrails/common/externalprocessor/README.md))
-that takes a provider-agnostic `messages` array and returns an `outcome` plus
-findings. This doc covers v1: a global, env-configured gate in front of every
-message Switch sends, blocking on a `BLOCKED` outcome.
+exposes a `/guardrails/check` endpoint on its external processor (server
+side) that takes a provider-agnostic `messages` array and returns an
+`outcome` plus findings. This doc covers v1: a global, env-configured gate in
+front of every message Switch sends, blocking on a `BLOCKED` outcome.
## Scope
@@ -51,14 +49,14 @@ interception point further down the stack.
## Enforcement flow
-1. Map the outgoing message to the hoot request shape:
+1. Map the outgoing message to the external processor's request shape:
```json
{"messages": [{"role": "<mapped>", "content": "<body>"}]}
```
Role mapping: `agent` → `assistant`, `human`/`bridge` → `user`.
2. `POST {switch_trust_endpoint}/guardrails/check` — the check-only endpoint
- added in [hoot#2397](https://github.com/sandbox-quantum/hoot/pull/2397) —
- with headers `x-guardrails-policy-id`, `x-flintai-api-key`, and three
+ on the guardrails external processor (server side) — with headers
+ `x-guardrails-policy-id`, `x-flintai-api-key`, and three
always-set identity headers Switch Trust uses to group checks:
- `x-agent-name`: a constant, `Switch Rooms Agents` — Switch has no single agent
to attribute a check to (a room can hold several, and a human-authored
@@ -117,9 +115,9 @@ on `TrustCheckResult.outcome`:
accidentally end up in a log line or a notice the way it could if findings
carried it around. The caller swaps in `redacted_content` before sending if
it's set. (The endpoint's own response doesn't carry a pre-sanitized
- message — hoot's "SanitizedMessages" is dashboard-ingestion-only state, not
- part of the `/guardrails/check` JSON body — so this redaction is Switch's
- own, built from the findings' detected text.) **Human-authored**: the
+ message — the processor's "SanitizedMessages" is dashboard-ingestion-only
+ state, not part of the `/guardrails/check` JSON body — so this redaction is
+ Switch's own, built from the findings' detected text.) **Human-authored**: the
redacted content is what reaches the room, but the sender would otherwise
never know their own words were altered — `CollaborationCore` also calls
the adapter's `admin_message(...)` back to the originating channel (a new
@@ -221,9 +219,9 @@ bootstrap stopgap, never a real deployment's config, and are gone: see
split across messages). Needs a role-mapping strategy for Switch's
multi-party rooms (which don't have a strict two-party turn structure) and a
decision on including/excluding system/admin notices.
-- **Tool calls / tool results**: the hoot endpoint supports `tool_calls` and
- `tool_result` message fields; Switch doesn't yet have an obvious mapping
- from its agent-protocol tool use onto that shape.
+- **Tool calls / tool results**: the external processor's endpoint supports
+ `tool_calls` and `tool_result` message fields; Switch doesn't yet have an
+ obvious mapping from its agent-protocol tool use onto that shape.
- **Per-tenant / per-workspace policy**: today it's one global policy for the
whole deployment. Multiple tenants wanting different policies needs a DB
table, migration, and an admin API — a materially bigger lift than the env