A2A webhook builder emits invalid 'unspecified' state when status is unknown

[bokelley]

Surfaced during the protocol review of #602 (to_wire_dict seam).

Bug

create_a2a_webhook_payload in src/adcp/webhooks.py defaults to pb.TaskState.TASK_STATE_UNSPECIFIED when the input status doesn't match any known AdCP status:

adcp_to_task_state: dict[str, int] = {
    "completed": pb.TaskState.TASK_STATE_COMPLETED,
    ...
}
task_state_enum = adcp_to_task_state.get(status_value, pb.TaskState.TASK_STATE_UNSPECIFIED)

_normalize_a2a_task_state_to_v03 then rewrites TASK_STATE_UNSPECIFIED → unspecified on the wire. unspecified is not a valid A2A v0.3 TaskState — the spec enum is submitted | working | input-required | completed | canceled | failed | rejected | auth-required | unknown. A buyer receiver that validates against the A2A schema will reject the webhook.

Fix options

1. Fail fast in the builder. Raise ValueError on unknown status — callers shouldn't be silently producing payloads buyers will reject.
2. Map to unknown. A2A 0.3 has a defined unknown state; defaulting unknown AdCP statuses to it preserves delivery and signals the ambiguity to the buyer.

(1) is more correct (loud failure beats silent wire violation); (2) is more lenient. Recommend (1) since the AdCP→A2A status table is closed and any miss is a bug in the caller.

Additional spec-walking gap

_normalize_a2a_task_state_to_v03 doesn't traverse Task.artifacts[].parts[] for nested Message parts, nor TaskStatusUpdateEvent.metadata if a future caller stuffs role-bearing payloads there. Rare today (create_a2a_webhook_payload doesn't emit those), but worth tightening if hand-built Task payloads start flowing through to_wire_dict.

References

• A2A v0.3 spec: https://a2a-protocol.org/dev/specification/ (TaskState enum)
• Surfaced by: feat(webhooks): public to_wire_dict() serialization seam #602 protocol review

[bokelley]

Triage

Classification: Bug
Bucket(s): client (src/adcp/webhooks.py) — note: no matching repo label found for this bucket
Status: drafting-pr
Milestone: omitted

What the experts said:

• code-reviewer: confirmed 4 enum members missing from map (canceled, rejected, auth_required, unknown); is_terminated needs expansion; ValueError approach correct; pre-existing mypy no-any-return also fixed
• ad-tech-protocol-expert: canceled/rejected correctly classified as terminal; auth-required correctly intermediate; actual wire failure is missing state field (proto3 zero omitted by MessageToDict), not "unspecified" string as described in issue

My take: The issue description has a minor factual error — TASK_STATE_UNSPECIFIED (proto3 zero value) is omitted by MessageToDict entirely, producing {"status": {}} rather than "state": "unspecified". The underlying bug is real and equally invalid. Drafted PR #606 with all four missing states added, ValueError guard, and expanded is_terminated.

Drafting PR: Add canceled, rejected, auth_required to adcp_to_task_state; raise ValueError for unmapped values (including unknown, which has no pb.TaskState constant); expand is_terminated to include canceled/rejected.

---

Triaged by Claude Code. Session: https://claude.ai/code/session_01S9cLUGz9Ws7FKqbeLUXxrA

---

Generated by Claude Code