Migrate from 3.0.5 details.status placeholder to AGENT_SUSPENDED / AGENT_BLOCKED codes (3.1 consolidation)

[bokelley]

Heads-up: AdCP 3.0.5 details.status placeholder is being consolidated in 3.1

AdCP 3.0.5 shipped error-details/agent-permission-denied.json carrying a placeholder shape for per-agent commercial-status rejections:

{
  "code": "PERMISSION_DENIED",
  "details": {
    "scope": "agent",
    "status": "suspended"   // or "blocked"
  }
}

That shape was a placeholder while the dedicated codes were being designed. AdCP 3.1 (PR adcontextprotocol/adcp#3906, in flight) consolidates the placeholder into two dedicated error codes:

Before (3.0.5)	After (3.1)
code: PERMISSION_DENIED, details: { scope: "agent", status: "suspended" }	code: AGENT_SUSPENDED (no details payload)
code: PERMISSION_DENIED, details: { scope: "agent", status: "blocked" }	code: AGENT_BLOCKED (no details payload)
code: PERMISSION_DENIED, details: { scope: "agent", reason: "sandbox_only" }	unchanged

The dedicated codes carry recovery: "terminal" directly at the wire level (the placeholder shape inherited PERMISSION_DENIED's correctable, which contradicted the no-retry MUST). The status field is removed from agent-permission-denied.json in 3.1 — this is not a deprecation window; envelopes carrying details.status will fail schema validation against 3.1.

Action

If this SDK has integrated against the 3.0.5 placeholder shape:

• Switch any code that emits PERMISSION_DENIED + scope:"agent" + status:"suspended"|"blocked" to emit AGENT_SUSPENDED / AGENT_BLOCKED directly.
• Switch any code that consumes details.status to branch on error.code === 'AGENT_SUSPENDED' | 'AGENT_BLOCKED' instead.
• The PERMISSION_DENIED + scope:"agent" + reason:"sandbox_only" path is unchanged and stays.

If this SDK has not integrated against the placeholder yet, no action — just integrate against the 3.1 shape directly when the dedicated codes land.

References

• Spec PR consolidating the placeholder: spec(errors): register AGENT_SUSPENDED / AGENT_BLOCKED + consolidate 3.0.5 details.status placeholder (closes #3871) adcp#3906
• Placeholder registration (3.0.5): spec(errors): register agent-permission-denied details + shared error-scope enum (closes #3883) adcp#3887
• Closes spec issue: spec(errors): register AGENT_SUSPENDED / AGENT_BLOCKED + standardize details.scope vocabulary adcp#3871
• Cross-tenant onboarding oracle clamp (unchanged in 3.1): error-handling.mdx Per-Agent Authorization Gate

[bokelley]

Triage

Classification: Bug (protocol conformance — recovery="correctable" contradicts the no-retry MUST for suspended/blocked agents even under 3.0.5)
Bucket(s): cross-repo, client, handlers (no matching labels in repo — gap noted in run summary)
Status: deferred

What the experts said:

• ad-tech-protocol-expert: Do not pre-write migration code against a draft schema; wait for adcp#3906 to ship and regen — hand-editing generated types creates silent drift. The correctable→terminal recovery flip is a breaking wire change (not a spec-correction for semver purposes), requiring at minimum a minor bump.
• code-reviewer: Correctly blocked — AGENT_SUSPENDED/AGENT_BLOCKED don't exist in the auto-generated enum and must not be hand-added. Scope when unblocked: regen error_code.py, update handler.py:477–498 (switch codes, flip recovery, drop details), ~6 docstring sites across handler.py/serve.py/registry.py/context.py, and update suspended/blocked test cases. sandbox_only has no implementation in this SDK — nothing to preserve.

My take: This is correctly gated on adcontextprotocol/adcp#3906 merging and the 3.1 schema publishing at the canonical source; no SDK pre-work is advisable. When adcp#3906 lands, the migration will require a minor-version bump (or major, depending on stability guarantees): both the correctable→terminal recovery flip and the PERMISSION_DENIED→AGENT_SUSPENDED/AGENT_BLOCKED code change are observable wire-contract breaks for callers.

Blocked-on: adcontextprotocol/adcp#3906 — resurfaces on merge

---

Triaged by Claude Code. Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code