feat(safety): say how far a block reached, and show what the model saw

The auto-block embed said a host was blocked and how many links, but not
whether that meant the whole domain, one pattern, or a single link. The
scope was tucked into the reason as a parenthetical on some paths and
absent on others. It is now its own field on every block embed, and the
reason carries only the model's reason.

The screenshot the model judged never left the agent run. fetch_page now
leaves it in a mutable contextvar holder, the same shape as the hard-hit
flag and for the same create_task reason, and the investigator attaches it
to both the block and the review embed. Discord takes it as a multipart
file the embed references by attachment name. Screening-tier blocks have
no render and attach nothing.

Author: Zingzy

infrastructure/ops_notify.py

@@ -14,6 +14,7 @@
 
 from __future__ import annotations
 
+import json
 from datetime import datetime, timezone
 from typing import Any, Protocol
 
@@ -22,6 +23,7 @@
 
 log = get_logger(__name__)
 
+_SHOT_NAME = "evidence.webp"
 _FOOTER = {
     "text": "spoo-me",
     "icon_url": "https://spoo.me/static/images/favicon.png",
@@ -66,6 +68,8 @@ async def safety_action(
         blocked_count: int,
         legacy_count: int,
         sample_url: str | None,
+        scope: str = "",
+        screenshot: bytes | None = None,
     ) -> bool: ...
 
     async def safety_review(
@@ -75,6 +79,7 @@ async def safety_review(
         trigger: str,
         sample_url: str | None,
         context: dict | None,
+        screenshot: bytes | None = None,
     ) -> bool: ...
 
 
@@ -215,12 +220,17 @@ async def safety_action(
         blocked_count: int,
         legacy_count: int,
         sample_url: str | None,
+        scope: str = "",
+        screenshot: bytes | None = None,
     ) -> bool:
         """Enforcement already happened — this states the ACTION TAKEN, it
         is not a request for one. ``legacy_count`` is v1/emoji links
-        blocked via their safety flag (same 451 as v2, reversible)."""
+        blocked via their safety flag (same 451 as v2, reversible).
+        ``scope`` is its own field: "host-wide" and "one link" are read
+        very differently by the person deciding whether to intervene."""
         fields: list[dict[str, Any]] = [
             {"name": "Destination Host", "value": f"```{host}```"},
+            {"name": "Scope", "value": f"```{scope or 'unspecified'}```"},
             {"name": "Reason", "value": f"```{reason}```"},
             {"name": "Trigger", "value": f"```{trigger}```"},
             {"name": "Links Blocked (v2)", "value": f"```{blocked_count}```"},
@@ -245,7 +255,9 @@ async def safety_action(
                 }
             ]
         }
-        return await self._deliver(self._report_url, payload, kind="safety_action")
+        return await self._deliver(
+            self._report_url, payload, kind="safety_action", screenshot=screenshot
+        )
 
     async def safety_review(
         self,
@@ -254,6 +266,7 @@ async def safety_review(
         trigger: str,
         sample_url: str | None,
         context: dict | None,
+        screenshot: bytes | None = None,
     ) -> bool:
         """No local source could judge this destination — a human decision
         is needed. Carries the trigger context so the decision takes
@@ -280,16 +293,35 @@ async def safety_review(
                 }
             ]
         }
-        return await self._deliver(self._report_url, payload, kind="safety_review")
+        return await self._deliver(
+            self._report_url, payload, kind="safety_review", screenshot=screenshot
+        )
 
     # ── Delivery ──────────────────────────────────────────────────────────────
 
-    async def _deliver(self, url: str, payload: dict[str, Any], *, kind: str) -> bool:
+    async def _deliver(
+        self,
+        url: str,
+        payload: dict[str, Any],
+        *,
+        kind: str,
+        screenshot: bytes | None = None,
+    ) -> bool:
         if not url:
             log.warning("ops_notify_not_configured", kind=kind)
             return False
         try:
-            response = await self._http.post(url, json=payload)
+            if screenshot:
+                # Discord webhooks take the image as a multipart file; the
+                # embed refers to it by attachment name.
+                payload["embeds"][0]["image"] = {"url": f"attachment://{_SHOT_NAME}"}
+                response = await self._http.post(
+                    url,
+                    data={"payload_json": json.dumps(payload)},
+                    files={"files[0]": (_SHOT_NAME, screenshot, "image/webp")},
+                )
+            else:
+                response = await self._http.post(url, json=payload)
             if response.status_code in (200, 204):
                 return True
             log.warning(

services/safety/analyzer.py

@@ -197,14 +197,14 @@ async def _handle_toxic(
                 matcher=lambda u: matching_blocked_pattern(u, (pattern,)) is not None,
                 reason=verdict.reason,
             )
-            scope_note = f"scoped to pattern {pattern}"
+            scope_note = f"pattern: {pattern}"
         else:
             result = await self._enforcer.block_matching(
                 event.host,
                 matcher=lambda u, _u=event.url: u == _u,
                 reason=verdict.reason,
             )
-            scope_note = "scoped to the judged URL"
+            scope_note = "the judged link only"
 
         await self._verdict_repo.upsert_verdict(
             event.host,
@@ -227,11 +227,12 @@ async def _handle_toxic(
             follow_up = "host-wide decision needs review"
         await self._notifier.safety_action(
             host=event.host,
-            reason=f"{verdict.reason} ({scope_note}; {follow_up})",
+            reason=f"{verdict.reason} ({follow_up})",
             trigger=event.trigger,
             blocked_count=result.blocked_count,
             legacy_count=result.legacy_count,
             sample_url=event.url,
+            scope=scope_note,
         )
 
     async def _warn_if_shared_carrier(
@@ -269,7 +270,9 @@ async def _reenforce(self, event: SafetyAnalyzeEvent, existing: VerdictDoc) -> b
                 matcher=lambda u: matching_blocked_pattern(u, (pattern,)) is not None,
                 reason=reason,
             )
-            await self._notify_reenforced(event, result, reason)
+            await self._notify_reenforced(
+                event, result, reason, scope=f"pattern: {pattern}"
+            )
             return matching_blocked_pattern(event.url, (pattern,)) is not None
         # links scope: already blocked and the create gate refuses the exact URL.
         return event.url == existing.sample_url
@@ -316,24 +319,28 @@ async def _screen_redirect(self, event: SafetyAnalyzeEvent) -> None:
             )
             await self._notifier.safety_action(
                 host=parts["host"],
-                reason=f"{reason} (reached through {event.host})",
+                reason=reason,
                 trigger=event.trigger,
                 blocked_count=result.blocked_count,
                 legacy_count=result.legacy_count,
                 sample_url=event.url,
+                scope=f"the judged link only (reached through {event.host})",
             )
 
-    async def _notify_reenforced(self, event, result, reason: str) -> None:
+    async def _notify_reenforced(
+        self, event, result, reason: str, scope: str = "host-wide"
+    ) -> None:
         """Blocked something: the operator hears about it. Zero blocks stays quiet."""
         if result.blocked_count + result.legacy_count == 0:
             return
         await self._notifier.safety_action(
             host=event.host,
-            reason=f"{reason} (re-enforced existing verdict)",
+            reason=reason,
             trigger=event.trigger,
             blocked_count=result.blocked_count,
             legacy_count=result.legacy_count,
             sample_url=event.url,
+            scope=f"{scope} (re-enforced existing verdict)",
         )
 
     async def _escalate(

services/safety/investigation.py

@@ -36,7 +36,12 @@
 from services.safety.events import SILENT_TRIGGERS, SafetyAnalyzeEvent
 from services.safety.feeds import REDIRECTOR_FEED
 from services.safety.providers import without_query
-from services.safety.tools import reset_hard_hit, saw_hard_hit
+from services.safety.tools import (
+    last_render_screenshot,
+    reset_hard_hit,
+    reset_last_render,
+    saw_hard_hit,
+)
 from shared.validators import is_valid_pattern, matching_blocked_pattern
 
 log = get_logger(__name__)
@@ -282,6 +287,7 @@ def __init__(
     async def investigate(self, event: SafetyAnalyzeEvent) -> None:
         bundle = await build_evidence_bundle(event, self._url_repo)
         reset_hard_hit()
+        reset_last_render()
         try:
             verdict: InvestigationVerdict = await self._runner.run(self._task, bundle)
         except LlmTaskFailed as exc:
@@ -371,6 +377,7 @@ async def _enact(
         verdict: InvestigationVerdict,
         decision: AuthorityDecision,
     ) -> None:
+        shot = last_render_screenshot() or None
         if decision.action == "block_host":
             result = await self._enforcer.block_host(event.host, reason=verdict.reason)
             await self._notifier.safety_action(
@@ -380,6 +387,8 @@ async def _enact(
                 blocked_count=result.blocked_count,
                 legacy_count=result.legacy_count,
                 sample_url=event.url,
+                scope="host-wide",
+                screenshot=shot,
             )
         elif decision.action == "block_aliases":
             if (
@@ -400,7 +409,7 @@ async def _enact(
                     result.blocked_count,
                     result.legacy_count,
                 )
-                scope_note = f"pattern proposed for the blocklist: {pattern}"
+                scope_note = f"pattern: {pattern} (proposed for the blocklist)"
             else:
                 pairs = await self._aliases_to_block(event)
                 if pairs:
@@ -425,11 +434,13 @@ async def _enact(
                 scope_note = "specific links only, host left serving"
             await self._notifier.safety_action(
                 host=event.host,
-                reason=f"{verdict.reason} ({scope_note})",
+                reason=verdict.reason,
                 trigger=event.trigger,
                 blocked_count=blocked_count,
                 legacy_count=legacy_count,
                 sample_url=event.url,
+                scope=scope_note,
+                screenshot=shot,
             )
         elif decision.action == "apply_list":
             if self._feed_repo is None:
@@ -469,6 +480,7 @@ async def _enact(
                 host=event.host,
                 trigger=event.trigger,
                 sample_url=event.url,
+                screenshot=shot,
                 context={
                     **(event.context or {}),
                     "classification": verdict.classification.value,

services/safety/tools.py

@@ -77,6 +77,31 @@ def reset_hard_hit() -> None:
     _hard_hit.set(_HardHitFlag())
 
 
+class _LastRender:
+    def __init__(self) -> None:
+        self.screenshot: bytes = b""
+        self.url: str = ""
+
+
+# Same mutable-holder shape as the hard-hit flag, for the same create_task
+# reason: fetch_page runs in a child task and must mutate, never rebind.
+_last_render: contextvars.ContextVar[_LastRender | None] = contextvars.ContextVar(
+    "safety_last_render", default=None
+)
+
+
+def reset_last_render() -> None:
+    _last_render.set(_LastRender())
+
+
+def last_render_screenshot() -> bytes:
+    """The most recent non-empty screenshot this investigation rendered, or
+    b"". It is the evidence the operator embed should show alongside the
+    verdict, since the model's reason describes what was in it."""
+    held = _last_render.get()
+    return held.screenshot if held is not None else b""
+
+
 def saw_hard_hit() -> bool:
     flag = _hard_hit.get()
     return flag is not None and flag.hit
@@ -523,6 +548,9 @@ async def fetch_page(url: str) -> str | ToolReturn:
         text = f"rendered via {result.egress}\nurl: {url}\n{trimmed}"
         if not result.screenshot:
             return text
+        held = _last_render.get()
+        if held is not None:
+            held.screenshot, held.url = result.screenshot, url
         return ToolReturn(
             return_value=f"{text}\nscreenshot: attached",
             content=[BinaryContent(data=result.screenshot, media_type="image/webp")],

tests/unit/infrastructure/test_ops_notify.py

@@ -100,3 +100,88 @@ async def test_embed_url_points_to_stats_page(self):
         await notifier.url_report("abc123", "spam", "1.2.3.4", "https://spoo.me/")
         embed = http.post.call_args.kwargs["json"]["embeds"][0]
         assert embed["url"] == "https://spoo.me/stats/abc123"
+
+
+def _action(notifier, **over):
+    base = dict(
+        host="evil.example",
+        reason="fake bank login",
+        trigger="sweep",
+        blocked_count=3,
+        legacy_count=0,
+        sample_url="https://evil.example/x",
+    )
+    base.update(over)
+    return notifier.safety_action(**base)
+
+
+class TestScopeField:
+    """ "host-wide" and "one link" are read very differently by the person
+    deciding whether to intervene, so scope is its own field, not a clause
+    tucked into the reason."""
+
+    async def test_scope_is_its_own_field(self):
+        notifier, http = _make()
+        await _action(
+            notifier, scope="pattern: ^https://sites\\.google\\.com/view/evil/.*"
+        )
+        fields = {
+            f["name"]: f["value"]
+            for f in http.post.call_args.kwargs["json"]["embeds"][0]["fields"]
+        }
+        assert (
+            fields["Scope"]
+            == "```pattern: ^https://sites\\.google\\.com/view/evil/.*```"
+        )
+        assert fields["Reason"] == "```fake bank login```"
+
+    async def test_missing_scope_is_named_not_omitted(self):
+        notifier, http = _make()
+        await _action(notifier)
+        fields = {
+            f["name"]: f["value"]
+            for f in http.post.call_args.kwargs["json"]["embeds"][0]["fields"]
+        }
+        assert fields["Scope"] == "```unspecified```"
+
+
+class TestScreenshotAttachment:
+    """The evidence the model judged should sit next to the verdict. Discord
+    takes it as a multipart file the embed points at by attachment name."""
+
+    async def test_block_embed_carries_the_screenshot_as_multipart(self):
+        import json
+
+        notifier, http = _make()
+        await _action(notifier, scope="host-wide", screenshot=b"webp!")
+        kw = http.post.call_args.kwargs
+        assert "json" not in kw
+        assert kw["files"]["files[0]"] == ("evidence.webp", b"webp!", "image/webp")
+        payload = json.loads(kw["data"]["payload_json"])
+        assert payload["embeds"][0]["image"] == {"url": "attachment://evidence.webp"}
+        assert payload["embeds"][0]["title"] == "Safety: destination auto-blocked"
+
+    async def test_review_embed_carries_the_screenshot_too(self):
+        import json
+
+        notifier, http = _make()
+        await notifier.safety_review(
+            host="h",
+            trigger="report",
+            sample_url="https://h/x",
+            context={"k": "v"},
+            screenshot=b"shot",
+        )
+        kw = http.post.call_args.kwargs
+        assert kw["files"]["files[0]"][1] == b"shot"
+        assert (
+            json.loads(kw["data"]["payload_json"])["embeds"][0]["image"]["url"]
+            == "attachment://evidence.webp"
+        )
+
+    async def test_no_screenshot_stays_plain_json(self):
+        notifier, http = _make()
+        await _action(notifier, scope="host-wide")
+        kw = http.post.call_args.kwargs
+        assert "json" in kw and "files" not in kw and "data" not in kw
+        assert "image" not in kw["json"]["embeds"][0]

tests/unit/services/safety/test_analyzer.py

@@ -641,8 +641,9 @@ async def test_reenforcement_that_blocks_new_links_notifies(self):
 
         await analyzer.analyze(_event())
 
-        reason = notifier.safety_action.await_args.kwargs["reason"]
-        assert "re-enforced" in reason
+        kw = notifier.safety_action.await_args.kwargs
+        assert kw["scope"] == "host-wide (re-enforced existing verdict)"
+        assert kw["reason"] == "old verdict"
 
     @pytest.mark.asyncio
     async def test_idempotent_reenforcement_stays_quiet(self):