feat(schema): register AGENT_SUSPENDED / AGENT_BLOCKED error codes

[bokelley]

Closes #3871

Summary

Extends the error-code vocabulary with two new codes for the buyer-agent commercial-relationship rejection surface introduced by BuyerAgentRegistry (adcp-client#1269). Without standard codes, every SDK and seller invents its own discriminator for "this buyer agent is not in good standing." The JS SDK is currently using PERMISSION_DENIED + scope:'agent' as a non-standard placeholder.

Non-breaking justification: Adds two new string enum values appended at the end of error-code.json (no reordering or removal) and two new error-details/ schemas (new files). Existing consumers that handle unknown codes via the recovery fallback (spec-required behavior) are unaffected.

Changes

• static/schemas/source/enums/error-code.json — AGENT_SUSPENDED (recovery: terminal) and AGENT_BLOCKED (recovery: terminal) appended to enum, with full enumDescriptions and enumMetadata entries including oracle-clamp normative language.
• static/schemas/source/error-details/agent-suspended.json — new. Intentionally empty (properties: {}, additionalProperties: false). Sellers MUST NOT include suspension reason, contract dates, or any per-agent commercial state.
• static/schemas/source/error-details/agent-blocked.json — new. Same clamp; no per-agent commercial state.
• docs/building/implementation/error-handling.mdx — new "Buyer-agent status" subsection with normative oracle-clamp rule, clamped-details requirement, and dispatch example distinguishing the two new codes from BILLING_NOT_PERMITTED_FOR_AGENT.
• docs/building/integration/accounts-and-agents.mdx — added third on-wire consequence bullet in the "Buyer-agent identity" section (billing gate + agent-status gate + per-agent defaults).

Design choices vs. issue proposal

The issue proposed standardizing error.details.scope as a shared vocabulary (extending billing-not-supported.json's ["capability", "account"] to include "agent"). Expert consultation ruled this out: neither new code has a gate-split to dispatch on (scope disambiguates two gates on BILLING_NOT_SUPPORTED; AGENT_SUSPENDED and AGENT_BLOCKED are already distinct codes). Standalone per-code schemas matching the billing-not-permitted-for-agent.json pattern are the correct shape. The issue's scope framing is noted in the changeset for the follow-up author.

Pre-PR review

• code-reviewer: approved — enum, enumDescriptions, enumMetadata all updated; both schemas structurally sound; changeset minor correct. Fixed header casing (sentence case), added default: arm to dispatch example, added cross-reference bullet to accounts-and-agents.mdx.
• ad-tech-protocol-expert: approved — oracle clamp language is equivalent to BILLING_NOT_PERMITTED_FOR_AGENT; scope omission is correct (no gate-split exists); both codes terminal is correct (re-onboarding is human-driven, not auto-retry); changeset level sound.

Build note

node_modules are not installed in the triage execution environment so npm run build could not run. JSON syntax verified programmatically (all three files parse cleanly). The schema additions are JSON-only (no TypeScript) — the tsc failures in build output are pre-existing missing-dependency errors unrelated to this diff.

Follow-up

Conformance fixtures for the oracle clamp are a follow-up (same pattern as billing-gate-conformance-and-resolver-naming.md following #3831).

Triage-managed PR. This bot does not currently iterate on
review comments or PR conversation threads (only on the source
issue). To unblock:

• Push fixup commits directly: gh pr checkout <num> →
  fix → push.
• Or re-trigger: comment /triage execute on the source
  issue.

See #3121
for context.

Session: https://claude.ai/code/session_01PSMBCdaXGreRTfZ7AXbKgT

---

Generated by Claude Code

[bokelley]

Closing — superseded. AGENT_SUSPENDED and AGENT_BLOCKED are already on main's static/schemas/source/enums/error-code.json with full enumDescriptions (oracle-clamp language, terminal recovery, sibling references) and enumMetadata entries. Other error codes already cite them by name. Drift dispositions also already track them at held-for-next-minor.