Skip to content

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

feat: handle REDACTED and ALERTED/ERRORED guardrail outcomes

Timo Bozsolik-Torres77cd957f79de
diff --git a/console/packages/plugins/src/switch-skill/SKILL.md b/console/packages/plugins/src/switch-skill/SKILL.md
index 9cf4632c3..4e86fdf1d 100644
--- a/console/packages/plugins/src/switch-skill/SKILL.md
+++ b/console/packages/plugins/src/switch-skill/SKILL.md
@@ -265,6 +265,11 @@ Rephrase and retry, or drop it. A human's message can be blocked the same way;
when it is, it never reaches the room or you at all, and the sender is told on
their own platform instead.
+Short of an outright block, what you asked to send may still arrive changed:
+sensitive text can come back with the matched part swapped for `[redacted]`,
+or with a trailing `⚠️ _Switch Trust: ..._` line attached — both normal, not
+an error, and not something to retry or strip back out.
+
## Questions and approvals
Native question forms can be answered in the Console or from the room. The
diff --git a/core/switch_core/bridges/agent/protocol/agent_core.py b/core/switch_core/bridges/agent/protocol/agent_core.py
index 5239a53c5..ee5823e39 100644
--- a/core/switch_core/bridges/agent/protocol/agent_core.py
+++ b/core/switch_core/bridges/agent/protocol/agent_core.py
@@ -126,6 +126,7 @@ from switch_core.trust.client import (
NullTrustClient,
TrustClient,
check_message,
+ trust_annotation,
)
if TYPE_CHECKING:
@@ -1227,16 +1228,24 @@ class AgentCore:
async def _enforce_trust(
self, room: RoomDescriptor, content: str, thread_root_id: str | None
- ) -> None:
+ ) -> str:
"""Check agent-authored content against Switch Trust before it is
- sent. Raises `GuardrailBlockedError` on a BLOCKED verdict, having
- already posted a notice in the room in place of the real content."""
+ sent. Returns the content to actually send — unchanged, redacted, or
+ carrying a short non-blocking annotation. Raises
+ `GuardrailBlockedError` on a BLOCKED verdict, having already posted a
+ notice in the room in place of the real content."""
check = await check_message(
self.trust_client, role="assistant", content=content
)
if check.blocked:
await self._post_trust_blocked_notice(room, thread_root_id)
raise GuardrailBlockedError(check)
+ 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
async def _post_trust_blocked_notice(
self, room: RoomDescriptor, thread_root_id: str | None
@@ -1327,7 +1336,7 @@ class AgentCore:
thread_root_id = await self._resolve_thread_root(
client, room.transport_room_id, thread_id
)
- await self._enforce_trust(room, content, thread_root_id)
+ content = await self._enforce_trust(room, content, thread_root_id)
event_id = await client.send_message(
room.transport_room_id,
content,
@@ -1796,7 +1805,7 @@ class AgentCore:
client = self.client_lifecycle.get_by_agent_id(agent_id)
if client is None:
raise ValueError("Agent client not running")
- await self._enforce_trust(room, detail, None)
+ detail = await self._enforce_trust(room, detail, None)
await client.send_message(
room.transport_room_id, f"*{detail}*", format="markdown", metered=True
)
@@ -2525,6 +2534,7 @@ 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)
await client.send_event(
room.transport_room_id,
"com.switch.task.finalise",
@@ -2535,7 +2545,6 @@ class AgentCore:
"outcome": outcome,
},
)
- await self._enforce_trust(room, outcome, None)
await client.send_message(
room.transport_room_id, outcome, format="markdown", metered=True
)
diff --git a/core/switch_core/bridges/collaboration/collaboration_core.py b/core/switch_core/bridges/collaboration/collaboration_core.py
index f7a40b0a9..ed45e771e 100644
--- a/core/switch_core/bridges/collaboration/collaboration_core.py
+++ b/core/switch_core/bridges/collaboration/collaboration_core.py
@@ -83,7 +83,12 @@ from switch_core.transport import (
RoomRef,
TransportError,
)
-from switch_core.trust.client import NullTrustClient, TrustClient, check_message
+from switch_core.trust.client import (
+ NullTrustClient,
+ TrustClient,
+ check_message,
+ trust_annotation,
+)
if TYPE_CHECKING:
from switch_core.bridges.agent.protocol.agent_connections import (
@@ -967,6 +972,11 @@ class CollaborationCore:
message_type=AdminMessageType.TRUST_BLOCKED.value,
)
return
+ 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}"
event_id = await human_actor.send_message(
transport_room_id,
content,
diff --git a/core/switch_core/trust/__init__.py b/core/switch_core/trust/__init__.py
index 0884191bc..3e0eba8f6 100644
--- a/core/switch_core/trust/__init__.py
+++ b/core/switch_core/trust/__init__.py
@@ -6,7 +6,9 @@ from switch_core.trust.client import (
TrustCheckResult,
TrustClient,
TrustFinding,
+ TrustOutcome,
check_message,
+ trust_annotation,
)
__all__ = [
@@ -17,5 +19,7 @@ __all__ = [
"TrustCheckResult",
"TrustClient",
"TrustFinding",
+ "TrustOutcome",
"check_message",
+ "trust_annotation",
]
diff --git a/core/switch_core/trust/client.py b/core/switch_core/trust/client.py
index 7e813b98c..a4f238ee9 100644
--- a/core/switch_core/trust/client.py
+++ b/core/switch_core/trust/client.py
@@ -19,10 +19,31 @@ import httpx
logger = logging.getLogger(__name__)
-_BLOCKED_OUTCOME = "GUARDRAIL_RESULT_OUTCOME_BLOCKED"
-
Role = Literal["user", "assistant"]
+# The outcome a check settles on. "errored" covers both what the wire protocol
+# calls GUARDRAIL_RESULT_OUTCOME_ERRORED (a detector itself failed, but the
+# engine still answered) and what `check_message` reports when the HTTP call
+# never completed at all — from a caller's perspective both are "this message
+# was not cleanly checked," and both get the same non-blocking annotation.
+#
+# The wire values below follow the GUARDRAIL_RESULT_OUTCOME_<NAME> convention
+# 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.
+TrustOutcome = Literal["ok", "blocked", "redacted", "alerted", "errored"]
+
+_OUTCOME_BY_WIRE_VALUE: dict[str, TrustOutcome] = {
+ "GUARDRAIL_RESULT_OUTCOME_OK": "ok",
+ "GUARDRAIL_RESULT_OUTCOME_BLOCKED": "blocked",
+ "GUARDRAIL_RESULT_OUTCOME_REDACTED": "redacted",
+ "GUARDRAIL_RESULT_OUTCOME_ALERTED": "alerted",
+ "GUARDRAIL_RESULT_OUTCOME_ERRORED": "errored",
+}
+
+_REDACTION_PLACEHOLDER = "[redacted]"
+
class GuardrailsCheckError(RuntimeError):
"""A check did not complete: network error, timeout, or a non-2xx answer."""
@@ -47,7 +68,10 @@ class GuardrailBlockedError(Exception):
class TrustFinding:
"""One detector hit. Deliberately narrower than the wire shape: no
`detected_string` — that is often the sensitive text itself (an email, a
- secret), and this travels into log lines and blocked-message notices."""
+ secret), and this travels into log lines and blocked-message notices.
+ (A REDACTED verdict's `detected_string`s are used once, inside
+ `HttpTrustClient.check`, to build `redacted_content`, and never stored
+ here.)"""
category: str
detector_name: str
@@ -56,10 +80,20 @@ class TrustFinding:
@dataclass(frozen=True)
class TrustCheckResult:
- blocked: bool
+ outcome: TrustOutcome
policy_id: str | None
policy_name: str | None
findings: tuple[TrustFinding, ...] = ()
+ # Set only when `outcome == "redacted"`: the checked content with each
+ # finding's detected text swapped for a placeholder. `None` otherwise,
+ # including when a REDACTED verdict carried no usable detected text to
+ # redact — callers must not send the original content in that case either,
+ # but that situation has not come up against the real endpoint yet.
+ redacted_content: str | None = None
+
+ @property
+ def blocked(self) -> bool:
+ return self.outcome == "blocked"
class TrustClient(Protocol):
@@ -70,7 +104,7 @@ class NullTrustClient:
"""Off: every message is allowed, and no request is made."""
async def check(self, *, role: Role, content: str) -> TrustCheckResult:
- return TrustCheckResult(blocked=False, policy_id=None, policy_name=None)
+ return TrustCheckResult(outcome="ok", policy_id=None, policy_name=None)
class HttpTrustClient:
@@ -122,28 +156,73 @@ class HttpTrustClient:
raise GuardrailsCheckError(
f"POST {self._url} answered a non-JSON body"
) from error
+
+ wire_outcome = str(body.get("outcome"))
+ outcome = _OUTCOME_BY_WIRE_VALUE.get(wire_outcome)
+ if outcome is None:
+ logger.warning(
+ "Switch Trust returned an unrecognised outcome %r; treating as "
+ "'errored' rather than silently allowing it through",
+ wire_outcome,
+ )
+ outcome = "errored"
+
+ raw_findings = body.get("findings") or []
findings = tuple(
TrustFinding(
category=finding.get("category", ""),
detector_name=finding.get("detector_name", ""),
severity=finding.get("severity"),
)
- for finding in body.get("findings") or []
+ for finding in raw_findings
)
+
+ redacted_content = None
+ if outcome == "redacted":
+ redacted_content = content
+ for finding in raw_findings:
+ detected = finding.get("detected_string")
+ if detected:
+ redacted_content = redacted_content.replace(
+ detected, _REDACTION_PLACEHOLDER
+ )
+
return TrustCheckResult(
- blocked=body.get("outcome") == _BLOCKED_OUTCOME,
+ outcome=outcome,
policy_id=body.get("policy_id"),
policy_name=body.get("policy_name"),
findings=findings,
+ redacted_content=redacted_content,
)
+def trust_annotation(result: TrustCheckResult) -> str | None:
+ """A short, non-blocking note to append to a message's body — the
+ in-chat indicator for ALERTED and a degraded/errored check. Reuses the
+ message's own body rather than a separate notice or a platform reaction:
+ `mark_activity` (the existing "working"/"queued" badge) is scoped to a
+ specific agent's identity on platforms that track per-agent reactions, and
+ a Switch Trust verdict belongs to no agent — retrofitting it would mean a
+ new cross-adapter primitive, out of proportion to a quiet heads-up.
+ `None` for every other outcome, including BLOCKED (handled separately) and
+ REDACTED (the redaction itself is the signal)."""
+ 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)_"
+ if result.outcome == "errored":
+ return "⚠️ _Switch Trust could not fully check this message_"
+ return None
+
+
async def check_message(
client: TrustClient, *, role: Role, content: str
) -> TrustCheckResult:
"""`client.check`, failing open: a Switch Trust outage degrades to
unchecked messages rather than to no messaging at all. Logged loudly
- either way, since this is the one place that gap is visible."""
+ either way, since this is the one place that gap is visible. Reported as
+ `outcome="errored"` rather than `"ok"`, so callers give it the same
+ quiet in-chat annotation as an engine-side error."""
try:
return await client.check(role=role, content=content)
except GuardrailsCheckError:
@@ -151,4 +230,4 @@ async def check_message(
"Switch Trust check failed; message allowed through unchecked",
exc_info=True,
)
- return TrustCheckResult(blocked=False, policy_id=None, policy_name=None)
+ return TrustCheckResult(outcome="errored", policy_id=None, policy_name=None)
diff --git a/core/tests/switch_core/trust/test_client.py b/core/tests/switch_core/trust/test_client.py
index c15fc8cba..fb66b16ab 100644
--- a/core/tests/switch_core/trust/test_client.py
+++ b/core/tests/switch_core/trust/test_client.py
@@ -16,6 +16,7 @@ from switch_core.trust.client import (
TrustCheckResult,
TrustFinding,
check_message,
+ trust_annotation,
)
@@ -128,7 +129,9 @@ async def test_null_client_always_allows():
async def test_check_message_fails_open_on_error():
client = _client(lambda request: httpx.Response(500, text="boom"))
result = await check_message(client, role="user", content="hi")
- assert result == TrustCheckResult(blocked=False, policy_id=None, policy_name=None)
+ assert result == TrustCheckResult(
+ outcome="errored", policy_id=None, policy_name=None
+ )
@pytest.mark.asyncio
@@ -144,7 +147,7 @@ async def test_check_message_passes_through_a_block():
def test_guardrail_blocked_error_names_the_categories():
result = TrustCheckResult(
- blocked=True,
+ outcome="blocked",
policy_id="pol_123",
policy_name="Default",
findings=(
@@ -154,3 +157,97 @@ def test_guardrail_blocked_error_names_the_categories():
),
)
assert "pii/email" in str(GuardrailBlockedError(result))
+
+
+async def test_a_redacted_outcome_swaps_the_detected_text():
+ def handler(request: httpx.Request) -> httpx.Response:
+ return httpx.Response(
+ 200,
+ json={
+ "outcome": "GUARDRAIL_RESULT_OUTCOME_REDACTED",
+ "findings": [
+ {
+ "category": "pii/email",
+ "detector_name": "PiiDetector",
+ "detected_string": "[email protected]",
+ "severity": "high",
+ }
+ ],
+ },
+ )
+
+ client = _client(handler)
+ result = await client.check(
+ role="user", content="email me at [email protected] please"
+ )
+
+ assert result.outcome == "redacted"
+ assert result.redacted_content == "email me at [redacted] please"
+ # Same guarantee as the blocked path: the raw text isn't exposed on the finding.
+ assert not hasattr(result.findings[0], "detected_string")
+
+
+async def test_a_redacted_outcome_with_no_detected_text_redacts_nothing():
+ client = _client(
+ lambda request: httpx.Response(
+ 200, json={"outcome": "GUARDRAIL_RESULT_OUTCOME_REDACTED", "findings": []}
+ )
+ )
+ result = await client.check(role="user", content="hello")
+ assert result.outcome == "redacted"
+ assert result.redacted_content == "hello"
+
+
+async def test_an_alerted_outcome_is_not_blocked():
+ client = _client(
+ lambda request: httpx.Response(
+ 200,
+ json={
+ "outcome": "GUARDRAIL_RESULT_OUTCOME_ALERTED",
+ "findings": [{"category": "pii/email", "detector_name": "PiiDetector"}],
+ },
+ )
+ )
+ result = await client.check(role="user", content="hi")
+ assert result.outcome == "alerted"
+ assert result.blocked is False
+ assert result.redacted_content is None
+
+
+async def test_an_unrecognised_outcome_is_treated_as_errored_not_allowed_silently():
+ client = _client(
+ lambda request: httpx.Response(200, json={"outcome": "SOMETHING_NEW"})
+ )
+ result = await client.check(role="user", content="hi")
+ assert result.outcome == "errored"
+
+
+def test_trust_annotation_names_the_categories_for_an_alert():
+ result = TrustCheckResult(
+ outcome="alerted",
+ policy_id=None,
+ policy_name=None,
+ findings=(
+ TrustFinding(
+ category="pii/email", detector_name="PiiDetector", severity=None
+ ),
+ ),
+ )
+ annotation = trust_annotation(result)
+ assert annotation is not None
+ assert "pii/email" in annotation
+
+
+def test_trust_annotation_covers_errored_the_same_way_as_degraded():
+ errored = TrustCheckResult(outcome="errored", policy_id=None, policy_name=None)
+ assert trust_annotation(errored) is not None
+
+
+def test_trust_annotation_is_none_for_ok_blocked_and_redacted():
+ for outcome in ("ok", "blocked", "redacted"):
+ result = TrustCheckResult(outcome=outcome, policy_id=None, policy_name=None)
+ assert trust_annotation(result) is None
diff --git a/docs/design/switch-trust-guardrails-v1.md b/docs/design/switch-trust-guardrails-v1.md
index 79ae2ed84..4fbb45ca7 100644
--- a/docs/design/switch-trust-guardrails-v1.md
+++ b/docs/design/switch-trust-guardrails-v1.md
@@ -14,8 +14,9 @@ message Switch sends, blocking on a `BLOCKED` outcome.
- One guardrails policy for the whole deployment (no per-tenant override).
- Configured by environment variables only — no gateway or console UI.
- Checks the single outgoing message only — no conversation history sent.
-- Only the `BLOCKED` outcome is acted on; `REDACTED`/`ALERTED`/`ERRORED` pass
- through unchanged.
+- All five outcomes are acted on: `BLOCKED` stops the send, `REDACTED`
+ replaces the content, `ALERTED`/`ERRORED` (and a Switch Trust outage) send
+ with a short non-blocking annotation. See §Enforcement flow.
- Text content only — no media/attachments, no tool call/tool result mapping.
These are deliberate v1 cuts, not an assessment that they're unneeded — see
@@ -23,17 +24,30 @@ Follow-ups.
## Where it hooks in
-The single point every message passes through, regardless of origin, is
-`Actor.send_message` (`core/switch_core/clients/actor.py:206`).
-`HumanActor`, `AgentActor`, `SystemActor`, and bridge actors all call it before
-it reaches `PostgresTransport._send` (`core/switch_core/transport/postgres.py:659`),
-which is where the row is actually persisted. The guardrails check runs in
-`Actor.send_message`, before the call into the transport — a blocked message
-never becomes a row.
-
-`SystemActor`'s own admin/notice sends are excluded from the check: they're
-Switch's own control-plane messages (including the blocked-notice this feature
-itself posts), not user or agent content.
+Not the fully generic `Actor.send_message` (`core/switch_core/clients/actor.py:206`)
+that was the original candidate: that method is also how Switch posts its own
+canned, system-generated text under an agent's or a bridge's identity (a
+join greeting, a command result, an auto-reply) — content nobody authored
+freely and that gains nothing from a guardrails check. Hooking there would
+have checked those too.
+
+Instead, the check runs at the point each kind of *freely-authored* content is
+actually about to be sent:
+
+- **Agent-authored**, in `AgentCore` (`core/switch_core/bridges/agent/protocol/agent_core.py`):
+ `send_message`, `update_status`, and `finalise_task` — the three places an
+ agent's own text (a reply, a status line, a task outcome) reaches a room.
+ All three call a shared `_enforce_trust(room, content, thread_root_id)`
+ helper.
+- **Human-authored**, in `CollaborationCore._handle_inbound_message`
+ (`core/switch_core/bridges/collaboration/collaboration_core.py`): the point
+ where an inbound platform message is about to become a
+ `human_actor.send_message(...)` call.
+
+Both sit directly in front of the actual send, so a blocked message never
+becomes a row — but each as a deliberately-chosen call site with the right
+context (room, thread, originating channel) rather than one generic
+interception point further down the stack.
## Enforcement flow
@@ -46,51 +60,74 @@ itself posts), not user or agent content.
added in [hoot#2397](https://github.com/sandbox-quantum/hoot/pull/2397) —
with headers `x-guardrails-policy-id` and `x-flintai-api-key`, short
timeout (2s default).
-3. `outcome == "GUARDRAIL_RESULT_OUTCOME_BLOCKED"` → block. Any other outcome
- (`OK`, `REDACTED`, `ALERTED`, `ERRORED`) → allow through unchanged.
-4. On block: `Actor.send_message` raises `GuardrailBlockedError` (carrying
- `outcome`, `findings`, `policy_id`) instead of calling the transport. No row
- is created.
-5. On network error, timeout, or non-2xx from Switch Trust: **fail open** —
- log a warning and let the message through unchecked. Blocking all of
- Switch's messaging on a guardrails-service outage is a worse failure mode
- than an unchecked message during an outage.
-
-## Differentiated handling by origin
-
-Both call sites catch `GuardrailBlockedError`; each already has the context to
-react appropriately for its direction.
-
-- **Agent-originated**, via `AgentProtocolCore.send_message`
- (`core/switch_core/bridges/agent/protocol/agent_core.py:1244`): catch the
- error, and instead of relaying the agent's real content, post a blocked
- notice into the room via `SystemActor.send_admin` with a new
- `AdminMessageType.TRUST_BLOCKED` (`core/switch_core/clients/admin_messages.py`).
- Every collaboration adapter (Slack, Mattermost, Discord, Teams, Telegram)
- already renders `admin_message()` as a platform-native system notice,
- distinct from an ordinary chat bubble — this is "visually stands out" for
- free. The agent's tool/API call gets back an error so it knows its response
- was blocked.
-- **Human/bridge-originated**, at the inbound ingestion call site in
- `core/switch_core/bridges/collaboration/collaboration_core.py` where a
- platform event becomes a `human_actor.send_message(...)` call: catch the
- error and call the adapter's `admin_message(...)` back to the **originating
- platform channel** directly. The row is never created, so the message never
- reaches the room or any agent — the notice goes straight back to the
- sender's platform, not into Switch.
-
-## Degraded-mode indicator (Switch Trust unreachable)
-
-v1 ships with a warning log only on fail-open. A lighter-weight in-chat
-indicator is worth adding as a fast-follow, reusing the mechanism Switch
-already uses for "agent is working" status rather than inventing a new one:
-every adapter implements `mark_activity()` (a reaction-emoji badge — 👀
-working / ⏳ queued, defined per-adapter, e.g.
-`core/switch_core/bridges/collaboration/slack/adapter.py:2049`) and
-`post_rich`/`update_rich` (an edited-in-place turn-status card). Teams has no
-reaction primitive (`supports_activity_reactions = False`), so it would only
-get the card-edit treatment. Deferred out of v1 to avoid coupling the first PR
-to the session/turn-rendering system — see Follow-ups.
+3. The outcome (mapped from the wire's `GUARDRAIL_RESULT_OUTCOME_*` values —
+ `ok` / `blocked` / `redacted` / `alerted` / `errored`) decides what happens
+ next — see §Outcome handling.
+4. On block: the caller raises `GuardrailBlockedError` (carrying `outcome`,
+ `findings`, `policy_id`) instead of sending. No row is created.
+5. On network error, timeout, non-2xx, or a response `HttpTrustClient` doesn't
+ recognise: **fail open** — `check_message` catches it, logs a warning, and
+ reports it to the caller as `outcome="errored"` rather than `"ok"`, so it
+ still gets the same quiet annotation an engine-side error would (see
+ below). Blocking all of Switch's messaging on a guardrails-service outage
+ is a worse failure mode than an unchecked message during an outage.
+
+## Outcome handling
+
+Each of the two call sites (§Where it hooks in) runs the check and then acts
+on `TrustCheckResult.outcome`:
+
+- **`blocked`** — raise `GuardrailBlockedError` instead of sending.
+ - **Agent-authored**: catch it in the three `AgentCore` methods, and instead
+ of the real content, post a notice into the room via `SystemActor.send_admin`
+ with a new `AdminMessageType.TRUST_BLOCKED`
+ (`core/switch_core/clients/admin_messages.py`). Every collaboration adapter
+ (Slack, Mattermost, Discord, Teams, Telegram) already renders
+ `admin_message()` as a platform-native system notice, distinct from an
+ ordinary chat bubble — this is "visually stands out" for free. The
+ agent's tool/API call gets back an error (HTTP 422 / an MCP tool error) so
+ it knows its response was blocked.
+ - **Human-authored**: catch it in `CollaborationCore._handle_inbound_message`
+ and call the adapter's `admin_message(...)` back to the **originating
+ platform channel** directly (`msg.channel_id`, `msg.root_id or
+ msg.message_ref`). The row is never created, so the message never reaches
+ the room or any agent — the notice goes straight back to the sender's
+ platform, not into Switch.
+- **`redacted`** — `HttpTrustClient.check` builds `redacted_content` itself:
+ for each finding, it substring-replaces `detected_string` in the checked
+ content with `[redacted]`, immediately, inside the client. `detected_string`
+ is never stored on `TrustFinding` or exposed elsewhere — only the already-
+ redacted result travels further, so the sensitive text itself can't
+ 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.)
+- **`alerted`** / **`errored`** (including a failed check, per above) — not
+ blocking. The caller appends a short line to the message body itself via
+ `trust_annotation()`, e.g. `⚠️ _Switch Trust: pii/email (not blocked)_` for
+ an alert, or `⚠️ _Switch Trust could not fully check this message_` for an
+ error — rather than a separate chat message or a platform reaction. See
+ below for why.
+- **`ok`** — unchanged.
+
+### Why an inline annotation and not a reaction badge
+
+The original sketch for a lightweight, non-disruptive indicator was to reuse
+`mark_activity()` — the reaction-emoji badge (👀 working / ⏳ queued) every
+adapter already implements for "agent is working" status. That turned out not
+to fit: `mark_activity`'s `agent_name` parameter is required because some
+platforms (Mattermost) give each agent's bot its own reaction, so the method
+has no way to add a reaction that belongs to no agent. A Switch Trust
+alert/error is a Switch-level concern, not any agent's — retrofitting it would
+mean a genuinely new cross-adapter primitive (touching every adapter), not a
+reuse of an existing one.
+
+Appending to the message body instead needs no adapter changes at all: it
+rides through the same `translate_outbound`/markdown pipeline every message
+already goes through, works identically on every platform, and stays attached
+to the message it's about, rather than becoming a second thing to read.
## Config
@@ -135,22 +172,24 @@ call site has to branch on whether the feature is on.
3. **Exception + admin message type** — add `GuardrailBlockedError` (new
module or alongside `transport` exceptions) and
`AdminMessageType.TRUST_BLOCKED` in `admin_messages.py`.
-4. **Wire the client into `Actor`** — inject `TrustClient` into `Actor`
- construction (exact DI point TBD when touching `ClientFactory`/`Actor.__init__`;
- follows the existing store/service injection pattern). Add the check at the
- top of `Actor.send_message`, skipped for `SystemActor`.
-5. **Agent-origin handling** — catch `GuardrailBlockedError` in
- `AgentProtocolCore.send_message`, post the `TRUST_BLOCKED` admin message,
- surface an error back to the caller.
-6. **Human/bridge-origin handling** — catch `GuardrailBlockedError` at the
- inbound ingestion call site in `collaboration_core.py`, call
- `adapter.admin_message(...)` back to the source channel instead of
- relaying.
+4. **Wire the client in** — inject `TrustClient` into `AgentCore` (new
+ required constructor param) and `CollaborationCore` (defaulted to
+ `NullTrustClient()` for the many tests that assemble one directly), built
+ once in `main.py` (`trust/setup.py::build_trust_client`) and threaded
+ through the same layers `telemetry` already is.
+5. **Agent-origin handling** — a shared `AgentCore._enforce_trust` helper,
+ called from `send_message`, `update_status`, and `finalise_task`: raises
+ `GuardrailBlockedError` on a block (having posted the `TRUST_BLOCKED`
+ admin message first), otherwise returns the content to actually send
+ (redacted or annotated as needed).
+6. **Human-origin handling** — the same outcome handling inline in
+ `CollaborationCore._handle_inbound_message`, before the
+ `human_actor.send_message(...)` call.
7. **Integration tests** (real Postgres, per repo convention) — a blocked
human message never creates a `messages` row; a blocked agent message
results in a `TRUST_BLOCKED` admin row instead of the real content; an
allowed message is unaffected; a Switch Trust timeout/error still delivers
- the message (fail-open).
+ the message (fail-open, annotated).
8. **`docs/old/`**: note the new config block in whichever doc lists
deployment env vars (none currently fully enumerates `SwitchConfig`, so
likely just a short mention near the other optional-integration blocks, if
@@ -163,8 +202,14 @@ call site has to branch on whether the feature is on.
Trust has its own deployment — tracked in Follow-ups.
- 2s timeout default, and `x-guardrails-policy-id` / `x-flintai-api-key`
headers, confirmed as-is.
-- Reaction-badge degraded-mode indicator deferred to a fast-follow rather than
- bundled into this PR.
+- The hook point moved from the originally-sketched `Actor.send_message` to
+ three `AgentCore` methods plus `CollaborationCore`'s inbound handler, to
+ avoid checking Switch's own canned/system text — see §Where it hooks in.
+- `REDACTED` and `ALERTED`/`ERRORED` are handled (client-side redaction and an
+ inline annotation, respectively) rather than deferred — see §Outcome
+ handling. The originally-sketched reaction-badge indicator was dropped in
+ favor of an inline annotation once `mark_activity`'s agent-scoping turned
+ out not to fit a Switch-level concern.
## Follow-ups (explicitly out of v1 scope)
@@ -179,9 +224,11 @@ call site has to branch on whether the feature is on.
- **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.
-- **Redaction / alert handling**: act on `REDACTED` (replace content with the
- engine's sanitized version) and `ALERTED` (log/flag without blocking)
- outcomes instead of only hard-blocking.
+- **A real cross-platform status indicator**: the inline-annotation approach
+ for `ALERTED`/`ERRORED` (§Outcome handling) is a pragmatic v1 choice. A
+ dedicated, Switch-level (not per-agent) reaction or status primitive across
+ adapters would be a nicer fast-follow, if the inline text proves too noisy
+ in practice.
- **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
@@ -190,7 +237,5 @@ call site has to branch on whether the feature is on.
operator dashboard or in Console's "server properties" — neither surface has
an existing settings page to extend today, so this is new UI work in either
home.
-- **Degraded-mode in-chat indicator**: the reaction-badge/turn-status
- treatment sketched above, once the core gate has shipped and proven out.
- **Media/attachment checks**: images and files aren't sent to Switch Trust in
v1.