replylayer 0.18.0__tar.gz → 0.22.0__tar.gz

{replylayer-0.18.0 → replylayer-0.22.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: replylayer
-Version: 0.18.0
+Version: 0.22.0
 Summary: Official Python SDK for ReplyLayer — email for AI agents
 License-Expression: MIT
 Keywords: agent,ai,email,mailbox,replylayer,sdk,webhook
@@ -443,6 +443,28 @@ if not status["active"] and status["privacy_ok"]:
 
 If `privacy_ok` is `False` the account's accepted privacy policy predates the disclosed sub-processor — re-accept the current Privacy Policy first (`enable_link_scanning` would otherwise raise a `409 PRIVACY_VERSION_TOO_OLD`). The async client exposes the same methods (`await rl.account.get_link_scanning_status()` / `await rl.account.enable_link_scanning(...)`).
 
+## Trusted instruction sources
+
+Every inbound message read carries `agent_safety_context` with `untrusted_content` `True` — the body is external data, not instructions for the agent to act on. Trusted instruction sources is an opt-in, **read-path-only** relaxation of that default for one specific, customer-designated, *verified* sender address per mailbox (address-grain only — there is no domain-wide grant). It does not change what a resulting send is allowed to do; the only related send-side control is a per-mailbox strict-recipient toggle, configured outside the SDK.
+
+The relaxation only applies on a read when **every** layer is satisfied, entirely on the server side: the platform feature is enabled, the mailbox's instruction-trust mode is on, the designated sender's message passed Mailgun sender verification (`verified_aligned`), the message scanned clean and is `available`, and the reading API key is a `role="agent"` key with the per-key capability enabled. There is no client-side opt-in — the SDK does not send any header or constructor flag to request this; a message either qualifies under the operator's configuration or it doesn't, and the response reflects that automatically:
+
+```python
+result = rl.messages.wait(mailbox["id"])
+msg = result["message"]
+ctx = msg.get("agent_safety_context") if msg else None
+if ctx and ctx.get("instruction_trust"):
+    # Gate passed: guidance was REPLACED with trusted-instruction wording (the
+    # agent may act on this verified sender's own explicit request in this
+    # message). untrusted_content is still True — this is metadata, not a
+    # content-safety judgment.
+    print(ctx["guidance"])
+    print(ctx["instruction_trust"])
+    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "mailgun"}
+```
+
+A human account owner enables the mailbox mode and the key's capability, and designates the trusted sender, from the dashboard (each a loosening change requiring session re-auth). Both the mailbox mode and the per-key capability default to off, so existing integrations are unaffected until a customer opts in. This is a read-path signal only — a copied or hijacked API key cannot self-grant the capability, and there is nothing for a client to set to request it.
+
 ## Mailbox identifiers
 
 Every SDK method that takes a `mailbox_id` argument accepts **either the mailbox's UUID or its name**. The server resolves names against the authenticated account's active mailboxes. `rl.messages.list("support-bot")` and `rl.messages.list("a1b2-…")` are equivalent.

{replylayer-0.18.0 → replylayer-0.22.0}/README.md

@@ -426,6 +426,28 @@ if not status["active"] and status["privacy_ok"]:
 
 If `privacy_ok` is `False` the account's accepted privacy policy predates the disclosed sub-processor — re-accept the current Privacy Policy first (`enable_link_scanning` would otherwise raise a `409 PRIVACY_VERSION_TOO_OLD`). The async client exposes the same methods (`await rl.account.get_link_scanning_status()` / `await rl.account.enable_link_scanning(...)`).
 
+## Trusted instruction sources
+
+Every inbound message read carries `agent_safety_context` with `untrusted_content` `True` — the body is external data, not instructions for the agent to act on. Trusted instruction sources is an opt-in, **read-path-only** relaxation of that default for one specific, customer-designated, *verified* sender address per mailbox (address-grain only — there is no domain-wide grant). It does not change what a resulting send is allowed to do; the only related send-side control is a per-mailbox strict-recipient toggle, configured outside the SDK.
+
+The relaxation only applies on a read when **every** layer is satisfied, entirely on the server side: the platform feature is enabled, the mailbox's instruction-trust mode is on, the designated sender's message passed Mailgun sender verification (`verified_aligned`), the message scanned clean and is `available`, and the reading API key is a `role="agent"` key with the per-key capability enabled. There is no client-side opt-in — the SDK does not send any header or constructor flag to request this; a message either qualifies under the operator's configuration or it doesn't, and the response reflects that automatically:
+
+```python
+result = rl.messages.wait(mailbox["id"])
+msg = result["message"]
+ctx = msg.get("agent_safety_context") if msg else None
+if ctx and ctx.get("instruction_trust"):
+    # Gate passed: guidance was REPLACED with trusted-instruction wording (the
+    # agent may act on this verified sender's own explicit request in this
+    # message). untrusted_content is still True — this is metadata, not a
+    # content-safety judgment.
+    print(ctx["guidance"])
+    print(ctx["instruction_trust"])
+    # {"version": "v1", "match": "address", "verified_domain": ..., "verdict": "verified_aligned", "provenance": "mailgun"}
+```
+
+A human account owner enables the mailbox mode and the key's capability, and designates the trusted sender, from the dashboard (each a loosening change requiring session re-auth). Both the mailbox mode and the per-key capability default to off, so existing integrations are unaffected until a customer opts in. This is a read-path signal only — a copied or hijacked API key cannot self-grant the capability, and there is nothing for a client to set to request it.
+
 ## Mailbox identifiers
 
 Every SDK method that takes a `mailbox_id` argument accepts **either the mailbox's UUID or its name**. The server resolves names against the authenticated account's active mailboxes. `rl.messages.list("support-bot")` and `rl.messages.list("a1b2-…")` are equivalent.

{replylayer-0.18.0 → replylayer-0.22.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "replylayer"
-version = "0.18.0"
+version = "0.22.0"
 description = "Official Python SDK for ReplyLayer — email for AI agents"
 readme = "README.md"
 license = "MIT"

{replylayer-0.18.0 → replylayer-0.22.0}/replylayer/__init__.py

@@ -13,13 +13,22 @@ from .errors import (
     # Migration 040 — scheduled-send error surface.
     SchedulingError,
     TimezoneRequiredError,
+    # Governed Email-Effect Contract v1 (Track 2) — strict-outcome errors.
+    EmailEffectError,
+    EmailEffectRejectedError,
+    EmailEffectHeldError,
+    EmailEffectRetryableError,
 )
 from .types import (
+    # Message delete response (0.20.0).
+    DeleteMessageResponse,
+    ReportResponse,
     # WS1 — star response types (0.16.0).
     MessageStarResponse,
     ThreadStarResponse,
     # WS6-SDK — async optimistic-ack (0.16.0).
     AsyncSendAck,
+    WebhookEventType,
     WebhookSummary,
     WebhookDeliverySummary,
     WebhookDeliveryStatus,
@@ -41,6 +50,9 @@ from .types import (
     GetUploadAttachmentResponse,
     # Migration 036 — recipient allowlist types.
     RecipientPolicyMode,
+    # Single "agent sends" control — derived view types.
+    AgentSendPolicy,
+    AgentSendRestrictedBy,
     AllowlistEntry,
     ListAllowlistResponse,
     AddAllowlistResponse,
@@ -62,6 +74,14 @@ from .types import (
     EnableLinkScanningResponse,
     EnableLinkScanningDisclosure,
     AgentSafetyContext,
+    InstructionTrustBasis,
+    # R5 — verified-sender signal.
+    SenderAuthVerdict,
+    SenderAuthentication,
+    SenderAuthenticationCompact,
+    # Governed Email-Effect Contract v1 (Track 2).
+    EmailEffect,
+    EffectStatus,
     MessageReceivedSafetySignal,
     MessageReceivedWebhookPayload,
     # PR 6 — HITL review queue webhook payload types.
@@ -81,9 +101,12 @@ from .types import (
     ScannerPolicy,
 )
 
-__version__ = "0.18.0"
+__version__ = "0.22.0"
 
 __all__ = [
+    # Message delete response (0.20.0).
+    "DeleteMessageResponse",
+    "ReportResponse",
     # WS1 — star response types (0.16.0).
     "MessageStarResponse",
     "ThreadStarResponse",
@@ -105,6 +128,14 @@ __all__ = [
     # Migration 040 — scheduled-send.
     "SchedulingError",
     "TimezoneRequiredError",
+    # Governed Email-Effect Contract v1 (Track 2).
+    "EmailEffectError",
+    "EmailEffectRejectedError",
+    "EmailEffectHeldError",
+    "EmailEffectRetryableError",
+    "EmailEffect",
+    "EffectStatus",
+    "WebhookEventType",
     "WebhookSummary",
     "WebhookDeliverySummary",
     "WebhookDeliveryStatus",
@@ -125,6 +156,8 @@ __all__ = [
     "ConsumedAttachmentResponse",
     "GetUploadAttachmentResponse",
     "RecipientPolicyMode",
+    "AgentSendPolicy",
+    "AgentSendRestrictedBy",
     "AllowlistEntry",
     "ListAllowlistResponse",
     "AddAllowlistResponse",
@@ -143,6 +176,10 @@ __all__ = [
     "EnableLinkScanningResponse",
     "EnableLinkScanningDisclosure",
     "AgentSafetyContext",
+    "InstructionTrustBasis",
+    "SenderAuthVerdict",
+    "SenderAuthentication",
+    "SenderAuthenticationCompact",
     "MessageReceivedSafetySignal",
     "MessageReceivedWebhookPayload",
     # PR 6 — HITL review queue.

{replylayer-0.18.0 → replylayer-0.22.0}/replylayer/_client.py

@@ -36,6 +36,7 @@ class ReplyLayer:
         timeout: float = 30.0,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         if not api_key:
             raise ReplyLayerError(
@@ -43,6 +44,12 @@ class ReplyLayer:
                 "api_key is required. Get yours at https://app.replylayer.ai/connect",
             )
 
+        # Governed Email-Effect Contract v1 (Track 2) — client-default for the
+        # `Prefer: outcome=strict` opt-in. When True, messages.send / .reply
+        # request a non-2xx (503/422/409) for a held/blocked outcome, raising the
+        # matching EmailEffectError subclass instead of resolving a 200. Default
+        # False is byte-identical to today (200 with `email_effect` in the body,
+        # no throw). Override per-call via `messages.send(strict_outcome=...)`.
         self._http = SyncHttpClient(
             api_key=api_key,
             base_url=base_url.rstrip("/"),
@@ -50,6 +57,7 @@ class ReplyLayer:
             timeout=timeout,
             max_retry_after_seconds=max_retry_after_seconds,
             on_retry=on_retry,
+            strict_outcome=strict_outcome,
         )
 
         self.domains = SyncDomains(self._http)
@@ -87,6 +95,7 @@ class AsyncReplyLayer:
         timeout: float = 30.0,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         if not api_key:
             raise ReplyLayerError(
@@ -94,6 +103,7 @@ class AsyncReplyLayer:
                 "api_key is required. Get yours at https://app.replylayer.ai/connect",
             )
 
+        # Governed Email-Effect Contract v1 (Track 2) — see ReplyLayer above.
         self._http = AsyncHttpClient(
             api_key=api_key,
             base_url=base_url.rstrip("/"),
@@ -101,6 +111,7 @@ class AsyncReplyLayer:
             timeout=timeout,
             max_retry_after_seconds=max_retry_after_seconds,
             on_retry=on_retry,
+            strict_outcome=strict_outcome,
         )
 
         self.domains = AsyncDomains(self._http)

{replylayer-0.18.0 → replylayer-0.22.0}/replylayer/_http.py

@@ -9,7 +9,7 @@ import httpx
 
 from .errors import ReplyLayerError, error_from_response
 
-_VERSION = "0.18.0"
+_VERSION = "0.22.0"
 _USER_AGENT = f"replylayer-sdk-py/{_VERSION}"
 _PROTECTED_HEADER_KEYS = frozenset({"authorization", "content-type", "user-agent"})
 
@@ -47,6 +47,7 @@ class SyncHttpClient:
         timeout: float,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         self._api_key = api_key
         self._base_url = base_url
@@ -54,6 +55,10 @@ class SyncHttpClient:
         self._timeout = timeout
         self._max_retry_after_seconds = max_retry_after_seconds
         self._on_retry = on_retry
+        # Governed Email-Effect Contract v1 (Track 2) — client default for the
+        # `Prefer: outcome=strict` opt-in. Read by SyncMessages/AsyncMessages
+        # send/reply as the fallback when the per-call `strict_outcome` is None.
+        self._strict_outcome = strict_outcome
         self._client = httpx.Client(timeout=timeout)
 
     def close(self) -> None:
@@ -194,6 +199,7 @@ class AsyncHttpClient:
         timeout: float,
         max_retry_after_seconds: float = _MAX_RETRY_AFTER_SECONDS,
         on_retry: OnRetry | None = None,
+        strict_outcome: bool = False,
     ) -> None:
         self._api_key = api_key
         self._base_url = base_url
@@ -201,6 +207,8 @@ class AsyncHttpClient:
         self._timeout = timeout
         self._max_retry_after_seconds = max_retry_after_seconds
         self._on_retry = on_retry
+        # Governed Email-Effect Contract v1 (Track 2) — see SyncHttpClient.
+        self._strict_outcome = strict_outcome
         self._client = httpx.AsyncClient(timeout=timeout)
 
     async def aclose(self) -> None:

{replylayer-0.18.0 → replylayer-0.22.0}/replylayer/errors.py

@@ -113,6 +113,92 @@ class TimezoneRequiredError(SchedulingError):
         )
 
 
+# Governed Email-Effect Contract v1 (Track 2) — strict-outcome opt-in errors.
+#
+# Raised ONLY when the caller opted in via `strict_outcome=True`
+# (Prefer: outcome=strict) AND the server maps a non-delivered terminal/held
+# outcome to a non-2xx. The error body carries the full governed payload
+# (`message_id`, `status`, `scan`, `hold_context`, `email_effect`) in
+# `details`, so a caller can branch retry-vs-edit-vs-escalate from the throw.
+#
+# Default (no `strict_outcome`) is byte-identical to today: the send/reply path
+# returns HTTP 200 with `email_effect` in the body and NONE of these is raised.
+#
+# Subclass of ReplyLayerError so generic catches still work; isinstance
+# EmailEffectError narrows to the strict-outcome family. Status-code → subclass:
+#   503 EMAIL_EFFECT_HELD_INFRA → EmailEffectRetryableError (carries retry_after)
+#   422 EMAIL_EFFECT_REJECTED   → EmailEffectRejectedError  (terminal content block)
+#   409 EMAIL_EFFECT_HELD       → EmailEffectHeldError      (releasable hold)
+# The factory recognizes the family by the body carrying `details.email_effect`
+# (mirroring the TS SDK), not by the `code` string.
+
+
+class EmailEffectError(ReplyLayerError):
+    """Base for the strict-outcome (``Prefer: outcome=strict``) error family.
+
+    ``email_effect`` is the parsed ``details.email_effect`` block (the governed
+    discriminator + booleans); ``scan`` is the parsed ``details.scan`` summary.
+    Both may be None if the server omitted them.
+    """
+
+    def __init__(
+        self,
+        status_code: int,
+        code: str,
+        message: str,
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(status_code, code, message, details)
+        d = details or {}
+        self.email_effect: dict[str, Any] | None = d.get("email_effect")
+        self.scan: dict[str, Any] | None = d.get("scan")
+
+
+class EmailEffectRejectedError(EmailEffectError):
+    """422 EMAIL_EFFECT_REJECTED — a genuine terminal content rejection.
+
+    ``email_effect.effect_status == 'blocked'`` (terminal=True). The agent's
+    correct action is edit-and-resend or escalate — NEVER retry the same body.
+    """
+
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(422, code, message, details)
+
+
+class EmailEffectHeldError(EmailEffectError):
+    """409 EMAIL_EFFECT_HELD — accepted into governance, releasable.
+
+    ``email_effect.effect_status == 'held_for_review'`` (releasable=True). The
+    send was quarantined / queued for human review — report "awaiting approval",
+    do not treat as a content error to fix by editing.
+    """
+
+    def __init__(self, code: str, message: str, details: dict[str, Any] | None = None) -> None:
+        super().__init__(409, code, message, details)
+
+
+class EmailEffectRetryableError(EmailEffectError):
+    """503 EMAIL_EFFECT_HELD_INFRA — a transient infrastructure hold.
+
+    ``email_effect.effect_status == 'held_infrastructure'`` (retryable=True): an
+    ``inference_error`` with NO genuine model judgment, so the content was never
+    judged. The agent's correct action is retry-later (back off on repeated
+    503s). ``retry_after`` mirrors the ``Retry-After`` header (None on absent /
+    non-numeric), reusing the same null-on-NaN parse as RateLimitError.
+    """
+
+    def __init__(
+        self,
+        code: str,
+        message: str,
+        headers: dict[str, str],
+        details: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(503, code, message, details)
+        ra = headers.get("retry-after")
+        self.retry_after: int | None = int(ra) if ra and ra.isdigit() else None
+
+
 def error_from_response(
     status: int,
     body: dict[str, Any],
@@ -139,6 +225,24 @@ def error_from_response(
     if code in _SCHEDULING_REASON_CODES:
         return SchedulingError(status, code, message, details)
 
+    # Governed Email-Effect Contract v1 (Track 2) — strict-outcome opt-in.
+    # Precedence-first BEFORE the generic status switch so a 503 becomes an
+    # EmailEffectRetryableError (not a generic ReplyLayerError), a 422 an
+    # EmailEffectRejectedError (not a plain ValidationError), and a 409 an
+    # EmailEffectHeldError — so `isinstance(err, EmailEffectError)` works
+    # uniformly across statuses. Gated on the body carrying `email_effect`
+    # (present ONLY when the request opted in AND the server applied the strict
+    # mapping), mirroring the TS SDK's `details?.email_effect` gate — robust to
+    # the exact `code` string. Any other status falls through to the generic
+    # switch unchanged.
+    if isinstance(details, dict) and details.get("email_effect") is not None:
+        if status == 422:
+            return EmailEffectRejectedError(code, message, details)
+        if status == 409:
+            return EmailEffectHeldError(code, message, details)
+        if status == 503:
+            return EmailEffectRetryableError(code, message, headers, details)
+
     if status == 401:
         return AuthenticationError(code, message, details)
     if status == 403:

{replylayer-0.18.0 → replylayer-0.22.0}/replylayer/resources/mailboxes.py

@@ -5,6 +5,7 @@ from urllib.parse import quote
 
 from .._http import AsyncHttpClient, SyncHttpClient
 from ..types import (
+    AgentSendPolicy,
     AttachmentAccessResponse,
     AttachmentAllowedFileFamilyRequest,
     AttachmentExposureMode,
@@ -456,6 +457,16 @@ class SyncMailboxes:
         # Migration 085 — thread-scoped reply bypass toggle. None means "do not
         # include the field in the PATCH".
         allow_thread_replies: bool | None = None,
+        # Migration 096 — R3 agent-send-containment opt-out (session/admin-only).
+        # None means "do not include the field in the PATCH".
+        agent_send_containment: bool | None = None,
+        # Single "agent sends" convenience control. None means "do not include
+        # the field". Mutually exclusive with raw recipient_policy_mode/
+        # agent_send_containment in the same call (the server returns 400).
+        agent_send_policy: AgentSendPolicy | None = None,
+        # Consent for opening the agent on an allowlist mailbox (also opens
+        # human sends). None/False omits it.
+        confirm_open_human_sends: bool | None = None,
         # PR 8.1 — per-detector redaction visibility. Pass {} to reset to
         # platform default; pass a partial map (e.g.
         # {"EMAIL_ADDRESS": {"redact": False}}) to disable redaction on
@@ -479,6 +490,12 @@ class SyncMailboxes:
             body["hitl_mode"] = hitl_mode
         if allow_thread_replies is not None:
             body["allow_thread_replies"] = allow_thread_replies
+        if agent_send_containment is not None:
+            body["agent_send_containment"] = agent_send_containment
+        if agent_send_policy is not None:
+            body["agent_send_policy"] = agent_send_policy
+        if confirm_open_human_sends:
+            body["confirm_open_human_sends"] = True
         if pii_redaction_config is not None:
             body["pii_redaction_config"] = pii_redaction_config
         return self._http.request("PATCH", f"/v1/mailboxes/{id}", body=body)
@@ -515,6 +532,41 @@ class SyncMailboxes:
         """
         return self.update(id, allow_thread_replies=allow)
 
+    def set_agent_send_containment(self, id: str, enabled: bool) -> dict[str, Any]:
+        """Migration 096 — toggle R3 agent-send-containment for this mailbox.
+
+        When ``True`` (the default), an agent-key send (NOT human/admin/session)
+        on a native-blocklist mailbox is run through the allowlist +
+        thread-participant gate so a hijacked agent can't exfiltrate to a new
+        recipient. Set ``False`` to deliberately open an uncontained agent send
+        path. Session/admin only server-side.
+        """
+        return self.update(id, agent_send_containment=enabled)
+
+    def set_agent_send_policy(
+        self,
+        id: str,
+        policy: AgentSendPolicy,
+        *,
+        confirm_open_human_sends: bool = False,
+    ) -> dict[str, Any]:
+        """Single "agent sends" control — the thin front door over
+        ``recipient_policy_mode`` + ``agent_send_containment`` (no separate
+        stored field). ``"open"`` lets the agent send to any new recipient;
+        ``"restricted"`` gates it. Session/admin only server-side.
+
+        Opening on an allowlist mailbox also opens human sends, so the server
+        returns 409 ``OPEN_AGENT_REQUIRES_OPEN_MAILBOX`` (with
+        ``details.also_opens_human_sends = True``) on the first call. Re-issue
+        with ``confirm_open_human_sends=True`` to atomically flip the mailbox to
+        blocklist + containment off.
+        """
+        return self.update(
+            id,
+            agent_send_policy=policy,
+            confirm_open_human_sends=confirm_open_human_sends,
+        )
+
     def set_sender_policy(
         self,
         id: str,
@@ -648,6 +700,16 @@ class AsyncMailboxes:
         # Migration 085 — thread-scoped reply bypass toggle. None = do not
         # include in the PATCH.
         allow_thread_replies: bool | None = None,
+        # Migration 096 — R3 agent-send-containment opt-out (session/admin-only).
+        # None = do not include in the PATCH.
+        agent_send_containment: bool | None = None,
+        # Single "agent sends" convenience control. None = do not include.
+        # Mutually exclusive with raw recipient_policy_mode/agent_send_containment
+        # in the same call (the server returns 400).
+        agent_send_policy: AgentSendPolicy | None = None,
+        # Consent for opening the agent on an allowlist mailbox (also opens
+        # human sends). None/False omits it.
+        confirm_open_human_sends: bool | None = None,
         # PR 8.1 — per-detector redaction visibility. Pass {} to reset to
         # platform default; pass a partial map to disable redaction on
         # selected detectors. None = do not include in the PATCH.
@@ -668,6 +730,12 @@ class AsyncMailboxes:
             body["hitl_mode"] = hitl_mode
         if allow_thread_replies is not None:
             body["allow_thread_replies"] = allow_thread_replies
+        if agent_send_containment is not None:
+            body["agent_send_containment"] = agent_send_containment
+        if agent_send_policy is not None:
+            body["agent_send_policy"] = agent_send_policy
+        if confirm_open_human_sends:
+            body["confirm_open_human_sends"] = True
         if pii_redaction_config is not None:
             body["pii_redaction_config"] = pii_redaction_config
         return await self._http.request("PATCH", f"/v1/mailboxes/{id}", body=body)
@@ -706,6 +774,39 @@ class AsyncMailboxes:
         """
         return await self.update(id, allow_thread_replies=allow)
 
+    async def set_agent_send_containment(self, id: str, enabled: bool) -> dict[str, Any]:
+        """Migration 096 — toggle R3 agent-send-containment for this mailbox (async).
+
+        When ``True`` (the default), an agent-key send on a native-blocklist
+        mailbox is run through the allowlist + thread-participant gate. Set
+        ``False`` to deliberately open an uncontained agent send path.
+        Session/admin only server-side.
+        """
+        return await self.update(id, agent_send_containment=enabled)
+
+    async def set_agent_send_policy(
+        self,
+        id: str,
+        policy: AgentSendPolicy,
+        *,
+        confirm_open_human_sends: bool = False,
+    ) -> dict[str, Any]:
+        """Single "agent sends" control — the thin front door over
+        ``recipient_policy_mode`` + ``agent_send_containment`` (async).
+
+        ``"open"`` lets the agent send to any new recipient; ``"restricted"``
+        gates it. Session/admin only server-side. Opening on an allowlist
+        mailbox also opens human sends, so the server returns 409
+        ``OPEN_AGENT_REQUIRES_OPEN_MAILBOX``; re-issue with
+        ``confirm_open_human_sends=True`` to atomically flip to blocklist +
+        containment off.
+        """
+        return await self.update(
+            id,
+            agent_send_policy=policy,
+            confirm_open_human_sends=confirm_open_human_sends,
+        )
+
     async def set_sender_policy(
         self,
         id: str,