Server: add configurable unknown-field policy before tool argument coercion

[bokelley]

Problem

Server-side tool calls can currently pass through permissive SDK/FastMCP request models before adopter-specific strict models see the raw arguments. That can allow unknown top-level tool fields to be accepted or silently dropped, especially on MCP.

In salesagent this caused a regression where dev/CI no longer failed loudly for payloads such as:

{
  "brief": "test ads",
  "nonsense_field": "bar"
}

The local workaround in salesagent PR #603 adds pre-validation hooks that:

• normalize legacy fields first
• reject unknown top-level fields in non-production/dev mode
• strip unsupported unknown fields in production/forward-compatible mode
• cover advertised write tools such as create_media_buy, not only read tools

Why this belongs in the SDK

This is a generic transport-boundary concern, not a seller-specific business rule. The SDK already owns:

• MCP/A2A dispatch
• request validation hooks
• generated tool schemas
• canonical error envelopes

If the SDK handles this centrally, every adopter gets consistent behavior before permissive Pydantic models can swallow extras.

Suggested API

One possible shape:

from adcp.validation import UnknownFieldPolicy, ValidationHookConfig

serve(
    handler,
    validation=ValidationHookConfig(
        unknown_fields=UnknownFieldPolicy.REJECT,  # or STRIP / IGNORE
    ),
)

or a simpler top-level option:

serve(handler, unknown_fields="reject")  # "strip" / "ignore"

The key is that this should run before tool argument validation/coercion on both MCP and A2A.

Expected behavior

• reject: fail loudly with canonical INVALID_REQUEST, including the unknown field path/name.
• strip: remove unsupported unknown top-level fields before validation, for forward-compatible production deployments.
• ignore: preserve current permissive behavior when adopters explicitly want it.
• Behavior should be transport-consistent for MCP and A2A.
• Regression tests should include mutating tools such as create_media_buy, because accepting unknown fields on write operations is the highest-risk path.

Reference

Salesagent fixed this locally in PR #603: bokelley/salesagent#603

[bokelley]

Triage

Classification: Feature request
Bucket(s): validation, handlers (no matching repo labels found)
Status: ready-to-implement

What the experts said:

• code-reviewer: Extend ValidationHookConfig with unknown_fields: Literal["reject","strip","ignore"] | None = None; implement as a dedicated gate in create_tool_caller after the pre-validation hook stage — not via pre_validation_hook (which would silently collide with adopter-supplied hooks); regression tests for mutating tools (create_media_buy) are a hard requirement before merge.
• dx-expert: Option B (extend ValidationHookConfig) is architecturally correct and consistent with the existing string-literal mode pattern across all 6+ factory entry points; document the distinction from ADCP_STRICT_VALIDATION (Pydantic model-level) vs. this new dispatcher gate, and record the SERVER_DEFAULT_VALIDATION default decision explicitly in the PR.

My take: Both experts converge — non-breaking with unknown_fields defaulting to "ignore". MCP and A2A consistency is free since both dispatch through create_tool_caller.

• src/adcp/validation/client_hooks.py — add UnknownFieldPolicy = Literal["reject", "strip", "ignore"] type alias and unknown_fields: UnknownFieldPolicy | None = None to ValidationHookConfig; export from validation/__init__.py. Leave SERVER_DEFAULT_VALIDATION unchanged.
• src/adcp/server/mcp_tools.py — in create_tool_caller, insert a gate after pre_validation_hook and before schema validation: key-check params against the tool's inputSchema.properties; on reject raise ADCPTaskError(INVALID_REQUEST, "<tool>: unknown field 'X'. Known fields: …"); on strip delete in place. Do not thread via pre_validation_hook.
• tests/ — reject and strip coverage for a mutating tool (create_media_buy) and a read tool; follow the _MinimalHandler fixture pattern in test_pre_validation_hooks.py.
• Non-breaking: unknown_fields defaults to None/"ignore", matching current behavior; no existing ValidationHookConfig construction call requires updating.

---

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

---

Generated by Claude Code