fix(decisioning): Tier 2 codes → spec-conformant PERMISSION_DENIED (#375)

[bokelley]

Summary

Resolves #375 (the rename portion). Tier 2 commercial-identity gate now raises spec-conformant PERMISSION_DENIED (and BILLING_NOT_PERMITTED_FOR_AGENT for the billing-capability path) instead of four SDK-invented error codes that violated the AdCP spec's cross-tenant onboarding-oracle clamp.

The parity-contract refactor (latency / headers / side-effects parity between the four denial paths) is deferred to follow-up issue #392 per the issue's stop-rule — that's a larger dispatch-path refactor than fits here. This PR closes the wire-code mismatch only.

Code changes

• _resolve_buyer_agent raises PERMISSION_DENIED on all four denial paths:
  • Recognized + suspended → details = {scope: "agent", status: "suspended", agent_url: ...}
  • Recognized + blocked → details = {scope: "agent", status: "blocked", agent_url: ...}
  • Unrecognized (registry miss / no credential / unknown status) → details omitted per the spec's omit-on-unestablished-identity rule.
• All four paths share a single _denied_message constant so error.message is not itself a side channel.
• All four paths use recovery="correctable" per the spec's enumMetadata for PERMISSION_DENIED. The details.scope == "agent" discriminator (when present) is the signal callers surface to a human operator rather than auto-retry — wire-level recovery semantics stay aligned with the spec.
• validate_billing_for_agent raises BILLING_NOT_PERMITTED_FOR_AGENT with details.rejected_billing (required) + optional details.suggested_billing (the alphabetically-first permitted mode), recovery="correctable" per spec. The full permitted_billing subset is not leaked — surfacing it on every rejection would let a misconfigured buyer probe and exfiltrate the billing matrix.

Verification

Both reviews (code-reviewer and protocol-expert) addressed:

• code-reviewer raised no blockers.
• protocol-expert flagged that recovery="terminal" on the denial paths conflicted with the spec's enumMetadata defaults for PERMISSION_DENIED (line 305-308 of error-code.json) and BILLING_NOT_PERMITTED_FOR_AGENT (line 349-352). Fixed in this PR — recovery is now correctable on all five denial paths. The human-vs-auto-retry semantic moved into details.scope, where it belongs.

BILLING_NOT_PERMITTED_FOR_AGENT is in the standard error-code enum at line 63 of error-code.json with full enumDescriptions and enumMetadata. The bundled details-payload schema is at error-details/billing-not-permitted-for-agent.json. No X_ vendor prefix is required and no upstream spec PR is needed.

Tests

• tests/test_tier2_spec_conformance.py (12 tests):
  • All four removed codes are no longer raised.
  • Recognized-but-denied paths carry scope + status in details.
  • Unrecognized paths omit details.
  • Billing path carries rejected_billing + optional suggested_billing; never leaks permitted_billing or agent_url.
• Updated tests/test_decisioning_buyer_agent_dispatch.py and tests/test_buyer_agent_registry.py to the spec-conformant wire shape and recovery="correctable".
• Full suite: 3154 passed, 0 failed locally.

Backwards compatibility

This is a behavior change for adopters who match on the old codes on the wire. The codes were just introduced in PRs #364 / #372 (recent — small blast radius). Adopters need to migrate to:

# Before
if e.code == "AGENT_SUSPENDED":
    ...
elif e.code == "AGENT_BLOCKED":
    ...
elif e.code == "REQUEST_AUTH_UNRECOGNIZED_AGENT":
    ...

# After
if e.code == "PERMISSION_DENIED":
    scope = e.details.get("scope")
    status = e.details.get("status")
    if scope == "agent" and status == "suspended":
        ...
    elif scope == "agent" and status == "blocked":
        ...
    else:  # scope absent → unrecognized agent (or unknown status)
        ...

# Billing
if e.code == "BILLING_NOT_PERMITTED_FOR_AGENT":
    rejected = e.details["rejected_billing"]  # always present
    suggested = e.details.get("suggested_billing")  # optional

Test plan

• ruff check src/ tests/ — clean (apart from 4 pre-existing E501 warnings unrelated to this PR).
• mypy src/adcp — Success: no issues found in 744 source files.
• pytest tests/test_tier2_spec_conformance.py tests/test_decisioning_buyer_agent_dispatch.py tests/test_buyer_agent_registry.py — 63 passed.
• pytest tests/ — 3154 passed, 0 failed.
• All pre-commit hooks pass (black, ruff, mypy, bandit, file-checks).

Refs

• Issue: Tier 2 commercial-identity error codes don't conform to AdCP spec — cross-tenant oracle risk #375
• Follow-up: Tier 2 commercial-identity gate: latency / headers / side-effects parity contract #392 (parity-contract refactor — latency / headers / side-effects parity).
• Spec enum: schemas/cache/enums/error-code.json (PERMISSION_DENIED enumMetadata at lines 305-308; BILLING_NOT_PERMITTED_FOR_AGENT at line 63 with enumMetadata at lines 349-352).

🤖 Generated with Claude Code