fix(decisioning): gate async-completion webhook on SPEC_WEBHOOK_TASK_TYPES (#932)

After #930, _project_handoff calls emit_terminal_completion_webhook for
every async task. SDK-internal, non-spec task types (notably
finalize_proposal, an interception of get_products in proposal_dispatch.py
that is not a spec wire op and not in SPEC_WEBHOOK_TASK_TYPES) flow through
with no webhook target wired, so the emitter logged a spurious "neither
webhook_sender nor webhook_supervisor is wired — terminal webhook silently
dropped" WARNING on every async finalize, even on a correctly-configured
server.

Hoist the SPEC_WEBHOOK_TASK_TYPES check to the top of the emitter (after
the enabled gate, before the target-None warning) and return silently for
non-spec task types, mirroring how the sync emitter gates. Non-spec types
rely on tasks/get polling / publishStatusChange per the documented rule
above SPEC_WEBHOOK_TASK_TYPES. Spec types with a real target still emit;
spec types with target=None (genuine misconfig) still warn.

Closes #931

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: bokelley

src/adcp/decisioning/webhook_emit.py

@@ -385,16 +385,25 @@ async def emit_terminal_completion_webhook(
 
     * ``enabled`` is False (operator opted out via
       ``auto_emit_completion_webhooks=False`` — they emit manually).
+    * ``method_name`` isn't in :data:`SPEC_WEBHOOK_TASK_TYPES`. This
+      gate runs FIRST, before any target check. SDK-internal,
+      non-spec task types (e.g. ``finalize_proposal``, an interception
+      of ``get_products`` in ``proposal_dispatch.py``) flow through
+      ``_project_handoff`` like any async task but legitimately have no
+      webhook target wired; per the spec-gate rule above
+      :data:`SPEC_WEBHOOK_TASK_TYPES`, they skip delivery and rely on
+      ``tasks/get`` polling / ``publishStatusChange``. Returning here
+      before the ``target is None`` branch keeps a correctly-configured
+      server from logging a spurious "silently dropped" WARNING on
+      every async non-spec task.
     * The request didn't carry ``push_notification_config.url``
       (polling-only via ``tasks/get`` — the spec permits this).
 
     Logs a WARNING when:
 
-    * ``target`` is None but the buyer DID register a push config —
-      their terminal notification is being silently dropped, the same
-      misconfig the sync gate warns on.
-    * ``method_name`` isn't in :data:`SPEC_WEBHOOK_TASK_TYPES` (the
-      adopter extended the tool surface beyond the spec enum).
+    * ``target`` is None but the buyer DID register a push config for a
+      SPEC-eligible task type — their terminal notification is being
+      silently dropped, the same misconfig the sync gate warns on.
 
     :param status: ``'completed'`` on success or ``'failed'`` on a
         terminal failure. The wire ``GeneratedTaskStatus`` enum.
@@ -409,6 +418,18 @@ async def emit_terminal_completion_webhook(
         if not enabled:
             return
 
+        # Spec gate FIRST — before any target / config inspection. Task
+        # types outside the closed spec enum (SDK-internal interceptions
+        # like ``finalize_proposal``) are not webhook-eligible; they skip
+        # silently and rely on ``tasks/get`` / ``publishStatusChange``.
+        # Running this ahead of the ``target is None`` branch is what
+        # stops a correctly-configured server from emitting a spurious
+        # "silently dropped" WARNING on every async non-spec task. The
+        # sync emitter (:func:`maybe_emit_sync_completion`) gates the
+        # same way.
+        if method_name not in SPEC_WEBHOOK_TASK_TYPES:
+            return
+
         config = getattr(params, "push_notification_config", None)
         if config is None and isinstance(params, dict):
             config = params.get("push_notification_config")
@@ -456,17 +477,6 @@ async def emit_terminal_completion_webhook(
         if result is not None:
             result = strip_credentials_from_wire_result(method_name, result)
 
-        if method_name not in SPEC_WEBHOOK_TASK_TYPES:
-            logger.warning(
-                "[adcp.decisioning] terminal %s webhook for async %s "
-                "(task_id=%s) skipped — tool not in spec task-type enum "
-                "(closed set per schemas/cache/enums/task-type.json).",
-                status,
-                method_name,
-                task_id,
-            )
-            return
-
         await target.send_mcp(
             url=url,
             task_id=task_id,

tests/test_decisioning_webhook_emit.py

@@ -35,6 +35,7 @@
     _BACKGROUND_WEBHOOK_TASKS,
     SPEC_WEBHOOK_TASK_TYPES,
     _extract_push_notification_url_and_token,
+    emit_terminal_completion_webhook,
     maybe_emit_sync_completion,
 )
 from adcp.server.base import ToolContext
@@ -377,6 +378,125 @@ class _Params:
     sender.send_mcp.assert_not_called()
 
 
+# ---- emit_terminal_completion_webhook spec-enum gate ----
+
+_SILENTLY_DROPPED = "silently dropped"
+
+
+@pytest.mark.asyncio
+async def test_terminal_emit_skips_non_spec_task_type_without_warning(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """SDK-internal, non-spec task types (e.g. ``finalize_proposal``, an
+    interception of ``get_products`` in ``proposal_dispatch.py``) flow
+    through ``_project_handoff`` like any async task. They legitimately
+    have no webhook target wired, so the spec gate must skip them
+    SILENTLY — no emission AND no "silently dropped" misconfig warning,
+    even when the buyer registered a push config. Regression: #931 — the
+    target-None warning fired on every async finalize on a
+    correctly-configured server."""
+
+    class _Config:
+        url = "https://buyer.example.com/wh"
+        token = None
+
+    class _Params:
+        push_notification_config = _Config()
+
+    target = AsyncMock()
+
+    with caplog.at_level("WARNING", logger="adcp.decisioning.webhook_emit"):
+        await emit_terminal_completion_webhook(
+            target=None,  # no target wired — the finalize_proposal reality
+            enabled=True,
+            method_name="finalize_proposal",  # NOT in SPEC_WEBHOOK_TASK_TYPES
+            params=_Params(),
+            status="completed",
+            task_id="task_finalize_1",
+            result={"proposal_id": "prop_1"},
+        )
+
+    # No emission attempted.
+    target.send_mcp.assert_not_awaited()
+    # And crucially: the spurious misconfig warning is ABSENT.
+    messages = [r.message for r in caplog.records]
+    assert not any(_SILENTLY_DROPPED in m for m in messages), (
+        f"non-spec task type must skip silently, but a 'silently dropped' "
+        f"warning was logged: {messages}"
+    )
+
+
+@pytest.mark.asyncio
+async def test_terminal_emit_fires_for_spec_task_type_with_target() -> None:
+    """A spec-eligible task type with a real target still emits the
+    terminal completion webhook unchanged — the gate only short-circuits
+    non-spec types."""
+
+    class _Config:
+        url = "https://buyer.example.com/wh"
+        token = "echo-back-token"
+
+    class _Params:
+        push_notification_config = _Config()
+
+    target = AsyncMock()
+
+    await emit_terminal_completion_webhook(
+        target=target,
+        enabled=True,
+        method_name="create_media_buy",  # in SPEC_WEBHOOK_TASK_TYPES
+        params=_Params(),
+        status="completed",
+        task_id="task_mb_1",
+        result={"media_buy_id": "mb_1"},
+    )
+
+    target.send_mcp.assert_awaited_once()
+    call_kwargs = target.send_mcp.await_args.kwargs
+    assert call_kwargs["url"] == "https://buyer.example.com/wh"
+    assert call_kwargs["task_type"] == "create_media_buy"
+    assert call_kwargs["status"] == "completed"
+    assert call_kwargs["task_id"] == "task_mb_1"
+    assert call_kwargs["result"] == {"media_buy_id": "mb_1"}
+    assert call_kwargs["token"] == "echo-back-token"
+
+
+@pytest.mark.asyncio
+async def test_terminal_emit_warns_for_spec_task_type_with_target_none(
+    caplog: pytest.LogCaptureFixture,
+) -> None:
+    """A SPEC-eligible task type with a push config registered but
+    ``target=None`` is a genuine misconfig — the buyer's terminal
+    notification is being dropped. That warning MUST still fire; the
+    spec gate only suppresses the warning for non-spec types."""
+
+    class _Config:
+        url = "https://buyer.example.com/wh"
+        token = None
+
+    class _Params:
+        push_notification_config = _Config()
+
+    with caplog.at_level("WARNING", logger="adcp.decisioning.webhook_emit"):
+        await emit_terminal_completion_webhook(
+            target=None,  # genuine misconfig for a spec task type
+            enabled=True,
+            method_name="create_media_buy",  # in SPEC_WEBHOOK_TASK_TYPES
+            params=_Params(),
+            status="completed",
+            task_id="task_mb_2",
+            result={"media_buy_id": "mb_2"},
+        )
+
+    messages = [r.message for r in caplog.records]
+    assert any(
+        "neither webhook_sender nor webhook_supervisor" in m
+        and _SILENTLY_DROPPED in m
+        and "buyer.example.com/wh" in m
+        for m in messages
+    ), f"expected target-None misconfig warning citing the buyer URL; got {messages}"
+
+
 # ---- PlatformHandler integration: sync-success fires, handoff doesn't ----