test(a2a): 1.0-pinned-to-0.3 reverse e2e + v4.0→v4.1 migration doc

[bokelley]

Summary

Ships two ready items from #263 (A2A 1.0 follow-ups). The other three items remain open on the parent pending cross-repo alignment or a maintainer call — see the triage comment on #263 for the breakdown.

• Item 4 — reverse-direction e2e test. tests/integration/test_a2a_wire_compat.py now covers 1.0 Python client → 0.3 JSON-RPC interface end-to-end, via force_a2a_version="0.3" against the same dual-advertising server fixture. Complements the existing 0.3-client → 1.0-server test. Also adds a failure-path guard that force_a2a_version="9.9" raises ADCPConnectionError loudly instead of dying deep in the SDK.
• Item 5 — subclasser migration doc. Adds MIGRATION_v4_0_to_v4_1.md documenting the three subclasser-facing breakages introduced by PR feat(a2a): migrate to a2a-sdk 1.0 with 0.3 wire-compat shim (Release-As: 4.1.0) #261: ServerError → A2AError, get_agent_info() dropping adcp_version / protocols_supported, and the a2a.types Pydantic → protobuf shift. Follows the MIGRATION_v3_to_v4.md pattern (a named migration file is the grep-able artifact subclassers actually find, vs. a hand-edited CHANGELOG entry that release-please would clobber).

Deferred to parent issue

• Item 1 (wrapper policy — docs say reject, Python unwraps): blocked on docs PR on adcontextprotocol/adcp branch bokelley/a2a-1.0-update. Flipping Python is a breaking change for buyers connected to ADK-backed sellers; soften-docs path is author's lean.
• Item 2 (webhook envelope StreamResponse wrapping): blocked on A2A 1.0 §4.3.3 re-read — StreamResponse is plausibly the streaming-transport frame discriminator, not a webhook envelope, in which case bare Task emission is correct.
• Item 3 (REJECTED / AUTH_REQUIRED extraction): current _process_task_response treats both as interim TaskStatus.SUBMITTED — contradicts the _NONTERMINAL_TASK_STATES docstring which calls REJECTED terminal. Fixing the classification is arguably correctness, but flips status == SUBMITTED branches to FAILED for any caller in the wild. Maintainer call.

What tested

• pytest tests/integration/test_a2a_wire_compat.py -v → 6 passed (4 existing + 2 new).
• ruff check src/ tests/integration/test_a2a_wire_compat.py → clean.
• mypy tests/integration/test_a2a_wire_compat.py → clean.

Expert consensus

• ad-tech-protocol-expert: reverse e2e is SAFE-TO-SHIP (purely additive, exercises public force_a2a_version pin).
• code-reviewer: reverse test ships now (reuses proven fixture, no flakiness risk); CHANGELOG 4.1.0 hand-edit rejected (release-please owns that file) — migration doc is the right primitive.
• dx-expert: subclassers hit ImportError / KeyError and grep the repo before reading CHANGELOGs — a named migration file is the artifact coding agents and humans reliably find.

Refs #263

Session: https://claude.ai/code/${CLAUDE_CODE_REMOTE_SESSION_ID}

---

Generated by Claude Code

[github-actions]

IPR Policy Agreement Required

Thank you for your contribution! Before we can accept your pull request, you must agree to our Intellectual Property Rights Policy.

By making a Contribution, you agree that:

• You grant the Foundation a perpetual, irrevocable, worldwide, non-exclusive, royalty-free copyright license to your Contribution
• You grant a patent license under any Necessary Claims
• You represent that you own or have sufficient rights to grant these licenses

To agree, please comment below with the exact phrase:

I have read the IPR Policy

You can read the full IPR Policy here.

---

I have read the IPR Policy

---

Brian O'Kelley (via Claude Code) seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You can retrigger this bot by commenting recheck in this Pull Request. Posted by the CLA Assistant Lite bot.}