feat(decisioning): emit AGENT_SUSPENDED / AGENT_BLOCKED dedicated codes (closes #409) (#748)

AdCP 3.1 (PR adcontextprotocol/adcp#3906, released as 3.1.0-beta.1)
consolidates the 3.0.5 PERMISSION_DENIED + details.status placeholder
for per-buyer-agent commercial-status rejections into dedicated codes
AGENT_SUSPENDED and AGENT_BLOCKED (recovery="terminal", no details
payload — the code itself is the discriminator, mirroring
BILLING_NOT_PERMITTED_FOR_AGENT).

Wire shape change in _resolve_buyer_agent:
- recognized + suspended: PERMISSION_DENIED + details.status="suspended"
  + recovery="correctable"  ->  AGENT_SUSPENDED + recovery="terminal"
- recognized + blocked:    PERMISSION_DENIED + details.status="blocked"
  + recovery="correctable"  ->  AGENT_BLOCKED + recovery="terminal"
- unrecognized paths (registry miss / no credential / unknown status):
  unchanged - still PERMISSION_DENIED with no details (cross-tenant
  onboarding-oracle clamp preserved).

The recovery="correctable" -> "terminal" flip is the spec's corrective
fix: the placeholder inherited PERMISSION_DENIED's correctable hint,
which contradicted the no-retry MUST for commercial-status rejections.

Uses the established KNOWN_NON_SPEC_CODES allowlist pattern (same
precedent as BILLING_NOT_PERMITTED_FOR_AGENT) - ADCP_VERSION stays
pinned at 3.0.7. Allowlist entries carry TODO-on-3.1-bundle-bump
markers so they auto-drop when the SDK eventually bumps to 3.1.

BREAKING (narrow): PermissionDeniedError(status=...) is removed. The
status field is gone from error-details/agent-permission-denied.json
in 3.1. Migrate to: raise AdcpError("AGENT_SUSPENDED", recovery="terminal")
for per-agent commercial status, or PermissionDeniedError(scope="agent",
reason="sandbox_only") for the remaining provisioning gate. Passing
status= now raises TypeError with a migration message; an explicit
**details guard prevents the kwarg from silently landing in
error.details and emitting a wire-invalid response.

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: bokelley

examples/buyer_agent_registry_sqlalchemy.py

@@ -368,11 +368,7 @@ def session_factory() -> Session:
     print("\n== suspended agent ==")
     suspended = await signing.resolve_by_agent_url("https://suspended-buyer.example/")
     print(f"  status: {suspended.status!r}")
-    print(
-        "  → framework dispatch raises "
-        "AdcpError(code='PERMISSION_DENIED', "
-        "details={'scope': 'agent', 'status': 'suspended', ...})"
-    )
+    print("  → framework dispatch raises " "AdcpError(code='AGENT_SUSPENDED', recovery='terminal')")
 
 
 if __name__ == "__main__":

src/adcp/decisioning/errors.py

@@ -43,13 +43,20 @@ class PermissionDeniedError(AdcpError):
     requested action under the seller's policies, or a required signed
     credential is missing/invalid.
 
-    :param scope: When the gate is a per-agent provisioning constraint,
-        set to ``'agent'`` (with ``status``); when billing-relationship,
-        set to ``'billing'``. Sellers MUST emit ``scope='agent'`` only
-        when buyer-agent identity has been established (signed-request
-        derivation or credential-to-agent mapping); otherwise omit.
-    :param status: When ``scope='agent'``, the per-agent state
-        (``'sandbox_only'``, etc.) — see
+    For per-agent commercial-status rejections (suspended / blocked),
+    raise :class:`AdcpError` with code ``"AGENT_SUSPENDED"`` /
+    ``"AGENT_BLOCKED"`` directly — those are dedicated AdCP 3.1 codes
+    with their own ``recovery="terminal"`` semantics, not flavors of
+    ``PERMISSION_DENIED``.
+
+    :param scope: When the gate is a per-agent non-status provisioning
+        constraint, set to ``'agent'`` (with ``reason``); when
+        billing-relationship, set to ``'billing'``. Sellers MUST emit
+        ``scope='agent'`` only when buyer-agent identity has been
+        established (signed-request derivation or credential-to-agent
+        mapping); otherwise omit.
+    :param reason: When ``scope='agent'``, the registered provisioning
+        gate that fired (``'sandbox_only'``, etc.) — see
         ``error-details/agent-permission-denied.json``.
     :param message: Optional human-readable override of the default.
     :param details: Additional fields merged into ``error.details``.
@@ -59,17 +66,37 @@ def __init__(
         self,
         *,
         scope: Literal["agent", "billing"] | None = None,
-        status: str | None = None,
+        reason: str | None = None,
         message: str | None = None,
         field: str | None = None,
         suggestion: str | None = None,
         **details: Any,
     ) -> None:
+        # Hard-reject the AdCP 3.0.5 placeholder ``status=`` kwarg.
+        # Without this, the kwarg would land in ``**details`` and emit
+        # ``error.details.status`` — a field 3.1 removed from
+        # ``agent-permission-denied.json``, which seller-side
+        # schema-validating receivers would reject. For per-agent
+        # commercial status, raise ``AdcpError`` with code
+        # ``"AGENT_SUSPENDED"`` / ``"AGENT_BLOCKED"`` directly.
+        if "status" in details:
+            raise TypeError(
+                "PermissionDeniedError.status= was removed in AdCP 3.1 "
+                "(spec PR adcontextprotocol/adcp#3906). The "
+                "placeholder details.status field is gone from "
+                "error-details/agent-permission-denied.json. Migrate to: "
+                "raise AdcpError('AGENT_SUSPENDED', recovery='terminal') "
+                "or AdcpError('AGENT_BLOCKED', recovery='terminal') for "
+                "per-agent commercial-status rejections, or pass "
+                "reason='sandbox_only' for the remaining provisioning "
+                "gate."
+            )
+
         merged_details: dict[str, Any] = dict(details)
         if scope is not None:
             merged_details["scope"] = scope
-        if status is not None:
-            merged_details["status"] = status
+        if reason is not None:
+            merged_details["reason"] = reason
 
         super().__init__(
             "PERMISSION_DENIED",

src/adcp/decisioning/handler.py

@@ -462,37 +462,39 @@ async def _resolve_buyer_agent(
       running a registry have implicitly opted out of unauthenticated
       traffic.
 
-    All four denial paths surface as ``code="PERMISSION_DENIED"`` to
-    match the spec enum and prevent the cross-tenant onboarding-oracle
-    risk: an attacker watching the wire MUST NOT be able to
-    distinguish "this agent_url is unrecognized at this seller" from
-    "this agent_url is recognized but currently denied". The
-    discriminator is in ``details``:
-
-    * recognized + suspended →
-      ``details = {scope: "agent", status: "suspended", agent_url: ...}``
-    * recognized + blocked →
-      ``details = {scope: "agent", status: "blocked", agent_url: ...}``
+    Per-agent commercial-status rejections surface as dedicated codes
+    (``AGENT_SUSPENDED`` / ``AGENT_BLOCKED``) per AdCP 3.1; the
+    unrecognized-identity path surfaces as ``PERMISSION_DENIED`` with
+    no ``details.scope``. This split prevents the cross-tenant
+    onboarding-oracle risk on the unrecognized path (no discriminator
+    that would let an attacker distinguish "this agent_url is
+    unrecognized at this seller" from a credential-shaped failure
+    against a known agent), while the dedicated codes carry their own
+    discriminator without needing a ``details`` payload.
+
+    * recognized + suspended → ``code="AGENT_SUSPENDED"``,
+      ``recovery="terminal"``, no ``details`` payload.
+    * recognized + blocked → ``code="AGENT_BLOCKED"``,
+      ``recovery="terminal"``, no ``details`` payload.
     * unrecognized (registry miss / no credential / unknown status) →
-      ``details`` OMITTED — scope MUST NOT be set on the unestablished-
-      identity path (omit-on-unestablished-identity rule).
+      ``code="PERMISSION_DENIED"``, no ``details`` — scope MUST NOT be
+      set on the unestablished-identity path
+      (omit-on-unestablished-identity rule).
 
     Note on parity: the *latency / headers / side-effects* parity
     contract between the recognized and unrecognized paths is tracked
     as a follow-up — the eager-raise pattern below still completes the
     unrecognized path on a different code path than the recognized
-    one. Renaming closes the wire-code mismatch; folding all four
-    paths through a common emit point with deliberate latency padding
-    and identical audit/metric side-effects is the next step.
-
-    :raises AdcpError: ``PERMISSION_DENIED`` (all four denial paths).
-        Recovery is ``correctable`` per the spec's ``enumMetadata``
-        for ``PERMISSION_DENIED``. The wire-level recovery hint is
-        independent of the resolution channel: the buyer cannot
-        auto-retry a commercial-identity rejection, but the
-        ``details.scope == "agent"`` discriminator (when present) is
-        the signal callers surface to a human operator rather than
-        loop on the request.
+    ones.
+
+    :raises AdcpError: ``AGENT_SUSPENDED`` / ``AGENT_BLOCKED`` /
+        ``PERMISSION_DENIED`` depending on path (see above). The
+        dedicated per-agent codes carry ``recovery="terminal"``: the
+        buyer cannot auto-retry a commercial-identity rejection, and
+        the code itself is the discriminator surfaced to a human
+        operator. ``PERMISSION_DENIED`` on the unrecognized path
+        carries ``recovery="correctable"`` per the spec's
+        ``enumMetadata``.
     """
     from adcp.decisioning.registry import (
         ApiKeyCredential,
@@ -554,26 +556,21 @@ async def _resolve_buyer_agent(
     if agent.status == "active":
         return agent
     if agent.status == "suspended":
+        # AdCP 3.1 dedicated code — the code itself is the discriminator,
+        # no ``details`` payload. ``recovery="terminal"`` per the spec
+        # (the placeholder ``PERMISSION_DENIED + details.status`` shape
+        # in 3.0.5 inherited ``correctable`` from PERMISSION_DENIED,
+        # which contradicted the no-retry MUST for this path).
         raise AdcpError(
-            "PERMISSION_DENIED",
+            "AGENT_SUSPENDED",
             message=_denied_message,
-            recovery="correctable",
-            details={
-                "scope": "agent",
-                "status": "suspended",
-                "agent_url": agent.agent_url,
-            },
+            recovery="terminal",
         )
     if agent.status == "blocked":
         raise AdcpError(
-            "PERMISSION_DENIED",
+            "AGENT_BLOCKED",
             message=_denied_message,
-            recovery="correctable",
-            details={
-                "scope": "agent",
-                "status": "blocked",
-                "agent_url": agent.agent_url,
-            },
+            recovery="terminal",
         )
     # Default-reject any non-active status the framework doesn't
     # recognize (typo, future enum value, adopter-custom string). A
@@ -1085,13 +1082,14 @@ async def _resolve_account(
         BEFORE calling ``AccountStore.resolve`` and stashes the result
         on ``ctx.metadata['adcp.buyer_agent']`` for :meth:`_build_ctx`
         to read into the typed :class:`RequestContext`. Suspended /
-        blocked / unrecognized agents are rejected here with
-        ``PERMISSION_DENIED`` (recognized-but-denied paths carry
-        ``details.scope="agent"`` + ``details.status``; the
-        unrecognized-agent path omits ``details`` so the wire shape
-        does not enumerate which ``agent_url``s are onboarded with
-        this seller) instead of the registry miss leaking into the
-        AccountStore as ``ACCOUNT_NOT_FOUND``.
+        blocked / unrecognized agents are rejected here with the
+        dedicated per-agent codes per AdCP 3.1:
+        suspended → ``AGENT_SUSPENDED``, blocked → ``AGENT_BLOCKED``
+        (both ``recovery="terminal"``, no ``details`` payload);
+        unrecognized → ``PERMISSION_DENIED`` with no ``details.scope``
+        so the wire shape does not enumerate which ``agent_url``s are
+        onboarded with this seller. This prevents the registry miss
+        from leaking into AccountStore as ``ACCOUNT_NOT_FOUND``.
         """
         await self._prime_auth_context(ctx)
         auth_info = self._extract_auth_info(ctx)

src/adcp/decisioning/serve.py

@@ -154,12 +154,13 @@ def create_adcp_server_from_platform(
         identity layer. When wired, the framework calls the registry
         BEFORE :meth:`AccountStore.resolve` to gate every request on
         the seller's commercial allowlist. Suspended / blocked /
-        unrecognized agents are rejected with structured
-        ``PERMISSION_DENIED`` errors (recognized-but-denied paths
-        carry ``details.scope="agent"`` + ``details.status``; the
-        unrecognized-agent path omits ``details`` so the wire shape
-        does not enumerate which ``agent_url``s are onboarded with
-        this seller). The resolved
+        unrecognized agents are rejected with structured errors:
+        suspended → ``AGENT_SUSPENDED``, blocked → ``AGENT_BLOCKED``
+        (both ``recovery="terminal"``, no ``details`` payload — the
+        code itself is the discriminator per AdCP 3.1); unrecognized
+        → ``PERMISSION_DENIED`` with no ``details.scope`` so the wire
+        shape does not enumerate which ``agent_url``s are onboarded
+        with this seller. The resolved
         :class:`adcp.decisioning.BuyerAgent` is threaded onto
         :attr:`RequestContext.buyer_agent` so platform methods can
         read commercial context (billing capabilities, default terms,

tests/test_decisioning_buyer_agent_dispatch.py

@@ -14,13 +14,15 @@
 * :class:`PlatformHandler` calls the registry BEFORE
   :meth:`AccountStore.resolve` when one is wired; the resolved
   :class:`BuyerAgent` is threaded onto :attr:`RequestContext.buyer_agent`.
-* Suspended / blocked / unknown-status agents reject with the
-  spec-conformant ``PERMISSION_DENIED`` code instead of leaking into
-  ``ACCOUNT_NOT_FOUND``. Recognized-but-denied paths carry
-  ``details.scope="agent"`` + ``details.status``; the unrecognized
-  paths (registry miss, no credential, unknown status) omit
-  ``details`` so the wire shape is indistinguishable per the
-  cross-tenant onboarding-oracle clamp.
+* Suspended / blocked agents reject with the AdCP 3.1 dedicated codes
+  ``AGENT_SUSPENDED`` / ``AGENT_BLOCKED`` (``recovery="terminal"``, no
+  ``details`` payload — the code itself is the discriminator).
+  Unrecognized paths (registry miss, no credential, unknown status)
+  surface ``PERMISSION_DENIED`` and omit ``details`` so the wire shape
+  does not enumerate which ``agent_url``s are onboarded with this
+  seller (cross-tenant onboarding-oracle clamp). All four paths reject
+  before ``AccountStore.resolve`` so the registry miss does not leak
+  into ``ACCOUNT_NOT_FOUND``.
 * No registry wired → existing dispatch path runs unchanged
   (back-compat for pre-trust beta adopters).
 """
@@ -694,13 +696,11 @@ async def get_products(self, req, ctx):
 
 
 @pytest.mark.asyncio
-async def test_suspended_agent_raises_permission_denied_terminal(executor) -> None:
-    """Status=suspended is rejected as ``PERMISSION_DENIED`` with
-    ``details.scope="agent"`` + ``details.status="suspended"``.
-    Wire-level ``recovery`` is ``correctable`` per the spec's
-    ``enumMetadata`` for ``PERMISSION_DENIED``; the
-    ``details.scope == "agent"`` discriminator is the signal callers
-    surface to a human operator rather than auto-retry."""
+async def test_suspended_agent_raises_agent_suspended_terminal(executor) -> None:
+    """Status=suspended is rejected as ``AGENT_SUSPENDED`` with
+    ``recovery="terminal"`` and no ``details`` payload (AdCP 3.1
+    dedicated code — the code itself is the discriminator, mirroring
+    ``BILLING_NOT_PERMITTED_FOR_AGENT``)."""
     from adcp.types import GetProductsRequest
 
     suspended = BuyerAgent(
@@ -730,21 +730,16 @@ async def get_products(self, req, ctx):
             GetProductsRequest(buying_mode="brief", brief="any"),
             tool_ctx,
         )
-    assert exc_info.value.code == "PERMISSION_DENIED"
-    assert exc_info.value.recovery == "correctable"
-    assert exc_info.value.details["scope"] == "agent"
-    assert exc_info.value.details["status"] == "suspended"
-    assert exc_info.value.details["agent_url"] == "https://suspended/"
+    assert exc_info.value.code == "AGENT_SUSPENDED"
+    assert exc_info.value.recovery == "terminal"
+    assert exc_info.value.details == {}
 
 
 @pytest.mark.asyncio
-async def test_blocked_agent_raises_permission_denied_terminal(executor) -> None:
-    """Status=blocked is rejected as ``PERMISSION_DENIED`` with
-    ``details.scope="agent"`` + ``details.status="blocked"``.
-    Wire-level ``recovery`` is ``correctable`` per the spec's
-    ``enumMetadata``; the ``details.scope == "agent"`` discriminator
-    signals callers to surface to a human operator rather than
-    auto-retry."""
+async def test_blocked_agent_raises_agent_blocked_terminal(executor) -> None:
+    """Status=blocked is rejected as ``AGENT_BLOCKED`` with
+    ``recovery="terminal"`` and no ``details`` payload (AdCP 3.1
+    dedicated code — the code itself is the discriminator)."""
     from adcp.types import GetProductsRequest
 
     blocked = BuyerAgent(
@@ -774,10 +769,9 @@ async def get_products(self, req, ctx):
             GetProductsRequest(buying_mode="brief", brief="any"),
             tool_ctx,
         )
-    assert exc_info.value.code == "PERMISSION_DENIED"
-    assert exc_info.value.recovery == "correctable"
-    assert exc_info.value.details["scope"] == "agent"
-    assert exc_info.value.details["status"] == "blocked"
+    assert exc_info.value.code == "AGENT_BLOCKED"
+    assert exc_info.value.recovery == "terminal"
+    assert exc_info.value.details == {}
 
 
 @pytest.mark.asyncio

tests/test_error_code_conformance.py

@@ -115,6 +115,25 @@
         "Per-agent billing gate raised by validate_billing_for_agent. "
         "In source/main (3.1), absent from 3.0.x dist bundles."
     ),
+    # TODO: drop when ADCP_VERSION >= 3.1.
+    # AdCP 3.1 (PR adcontextprotocol/adcp#3906) consolidates the 3.0.5
+    # `PERMISSION_DENIED + details.status` placeholder into dedicated
+    # codes for per-agent commercial-status rejections. The code itself
+    # is the discriminator (no `details` payload), mirroring
+    # `BILLING_NOT_PERMITTED_FOR_AGENT`. Both carry `recovery="terminal"`
+    # at the wire level — the placeholder shape inherited
+    # `PERMISSION_DENIED`'s `correctable`, which contradicted the
+    # no-retry MUST. Raised by `_resolve_buyer_agent` in
+    # `adcp.decisioning.handler` when `BuyerAgent.status` is
+    # "suspended" / "blocked" respectively.
+    "AGENT_SUSPENDED": (
+        "Per-agent suspended status raised by _resolve_buyer_agent. "
+        "In source/main (3.1.0-beta.1+), absent from 3.0.x dist bundles."
+    ),
+    "AGENT_BLOCKED": (
+        "Per-agent blocked status raised by _resolve_buyer_agent. "
+        "In source/main (3.1.0-beta.1+), absent from 3.0.x dist bundles."
+    ),
 }
 
 CANONICAL_CODES: frozenset[str] = frozenset(member.value for member in ErrorCode)

tests/test_mechanical_helpers.py

@@ -157,10 +157,10 @@ def test_default_code_and_recovery(self) -> None:
         assert err.code == "PERMISSION_DENIED"
         assert err.recovery == "correctable"
 
-    def test_scope_and_status_in_details(self) -> None:
-        err = PermissionDeniedError(scope="agent", status="sandbox_only")
+    def test_scope_and_reason_in_details(self) -> None:
+        err = PermissionDeniedError(scope="agent", reason="sandbox_only")
         assert err.details["scope"] == "agent"
-        assert err.details["status"] == "sandbox_only"
+        assert err.details["reason"] == "sandbox_only"
 
     def test_billing_scope(self) -> None:
         err = PermissionDeniedError(scope="billing")
@@ -171,13 +171,25 @@ def test_message_override(self) -> None:
         assert "custom denial reason" in str(err)
 
     def test_extra_details_forwarded(self) -> None:
-        err = PermissionDeniedError(scope="agent", reason="sandbox_only")
+        err = PermissionDeniedError(scope="agent", reason="sandbox_only", extra_key="extra_val")
         assert err.details["reason"] == "sandbox_only"
+        assert err.details["extra_key"] == "extra_val"
 
     def test_field_forwarded(self) -> None:
         err = PermissionDeniedError(field="governance_context")
         assert err.field == "governance_context"
 
+    def test_status_kwarg_rejects_with_migration_message(self) -> None:
+        """AdCP 3.1 removed the placeholder ``details.status`` field. Adopters
+        who wrote ``PermissionDeniedError(scope="agent", status="suspended")``
+        against 3.0.5 must migrate to ``AdcpError("AGENT_SUSPENDED", ...)``.
+        Without an explicit guard, ``status=`` would silently land in
+        ``**details`` and emit a wire-invalid response."""
+        with pytest.raises(TypeError) as exc:
+            PermissionDeniedError(scope="agent", status="suspended")
+        assert "AGENT_SUSPENDED" in str(exc.value)
+        assert "AdCP 3.1" in str(exc.value)
+
 
 class TestAuthRequiredError:
     def test_subclass_and_code(self) -> None: