Skip to content

Server: support composing pre-validation hooks per tool #859

Closed

Description

@bokelley

Problem

serve(pre_validation_hooks=...) currently accepts a single callable per tool name. That makes SDK-provided hooks and adopter-specific hooks hard to compose safely.

In salesagent, we needed to keep the SDK's built-in spec_compat behavior while adding a local strict unknown-field check. Because the hook map is one callable per tool, the app had to manually wrap _spec_compat_hooks_impl() and preserve ordering:

  1. run SDK compatibility hook
  2. run adopter request normalization
  3. run strict unknown-field policy

This is fragile and easy for adopters to get wrong. It also encourages use of private SDK internals when the public compat hook is deprecated/noisy in test contexts.

Why this belongs in the SDK

Hook ordering and composition are framework concerns. The SDK already owns the pre-validation hook invocation point for MCP and A2A, so it is the right layer to provide a small composition helper or first-class multi-hook support.

Suggested API options

Support multiple hooks per tool:

serve(
    handler,
    pre_validation_hooks={
        "get_products": [sdk_compat_hook, local_normalizer, strict_unknown_fields],
        "create_media_buy": [local_normalizer, strict_unknown_fields],
    },
)

or provide an explicit helper:

from adcp.server import compose_pre_validation_hooks, spec_compat_hooks

serve(
    handler,
    pre_validation_hooks=compose_pre_validation_hooks(
        spec_compat_hooks(),
        local_hooks,
        unknown_field_hooks,
    ),
)

Expected behavior

  • Preserve deterministic ordering.
  • Make composition work the same for MCP and A2A.
  • Avoid requiring adopters to copy SDK hook code or call private _spec_compat_hooks_impl().
  • Provide useful type hints for (tool_name, args) -> args.
  • Include tests for overlapping tool names, especially get_products and sync_creatives.

Reference

Salesagent needed a local wrapper in PR #603: bokelley/salesagent#603

Activity

  1. added
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 25, 2026
  2. bokelley commented on May 25, 2026

    @bokelley
    ContributorAuthor

    Triage

    Classification: Feature request
    Bucket(s): handlers, middleware
    Status: ready-to-implement

    What the experts said:

    • code-reviewer: Option B (compose_pre_validation_hooks helper) is safer — leaves the PreValidationHooks public type alias unchanged; internally normalize lists in create_tool_caller. All three call sites (mcp_tools.py, a2a_server.py, serve.py) must be updated atomically or the A2A transport silently diverges. Error messages in a composed chain must identify which hook raised (index + __name__).
    • dx-expert: Option A (list per tool) is more intuitive DX; follows established middleware-chain patterns. Points out three inconsistent type annotations for pre_validation_hooks across serve.py:601 (Callable[..., Any]), a2a_server.py:184 (dict[str, Any]), and mcp_tools.py:2438 (precise typed signature) — fix annotation consistency as part of this work. Recommends exporting PreValidationHook (singular) alongside the existing PreValidationHooks alias.

    My take: Both experts converge on a non-breaking change — widen the per-tool value to Callable | list[Callable] internally while also shipping a compose_pre_validation_hooks() helper for the "merge two separate hook dicts" use case. The annotation inconsistency and stale spec_compat.py:265 docstring should be fixed in the same PR. PR authorization gate not yet met; posting implementation brief.

    Implementation scope:

    • src/adcp/server/spec_compat.py — add PreValidationHook = Callable[[str, dict[str, Any]], dict[str, Any]] type alias; update PreValidationHooks value type to PreValidationHook | list[PreValidationHook]; remove/update line 264–266 ("only one callable per tool name" is now false); update _spec_compat_hooks_impl docstring.
    • src/adcp/server/mcp_tools.py (~line 2087) — in create_tool_caller, normalize list-of-hooks to a single chained callable before the if pre_validation_hook is not None: branch. Chain must be deterministic left-to-right; exception message must include hook chain index + callable.__name__.
    • src/adcp/server/a2a_server.py (line 211) and src/adcp/server/serve.py (line 2317) — same normalization; all three .get(name) extraction sites must handle list values; fix a2a_server.py:184 annotation from dict[str, Any] to PreValidationHooks.
    • New helper compose_pre_validation_hooks(*dicts: PreValidationHooks) -> PreValidationHooks — merges per-key via chaining (left-to-right), additive (keys not in earlier dicts are preserved). Place in a new src/adcp/server/_hooks.py (not in spec_compat.py, which is deprecated toward 6.0); re-export from adcp.server.__init__.
    • src/adcp/server/__init__.py — add PreValidationHook (singular) and compose_pre_validation_hooks to __all__; fix serve() annotation on line 601 to PreValidationHooks.
    • tests/ — cover: (a) list with overlapping tool names (get_products, sync_creatives); (b) ordering: first callable output feeds second; (c) error attribution: raising hook surfaces index + name in INVALID_REQUEST message; (d) MCP + A2A call sites produce identical chaining behavior; (e) compose_pre_validation_hooks merge semantics (two dicts with shared key produces a two-hook chain).
    • Non-breaking rationale: existing dict[str, Callable] callers satisfy the widened Callable | list[Callable] union at both runtime and mypy; no public symbol removed or renamed.

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


    Generated by Claude Code

  3. added and removed
    claude-triagingTriage routine is actively working on this issue (1-3 min)
    on May 25, 2026
  4. bokelley commented on Jun 6, 2026

    @bokelley
    ContributorAuthor

    The core of this — per-tool pre-validation hook composition — shipped in #860: PreValidationHook, PreValidationHookChain, PreValidationHooks, and compose_pre_validation_hooks() are live in src/adcp/server/spec_compat.py, ordered chains are applied in mcp_tools.py, and they're threaded through a2a_server.py and serve().

    Keeping this open as the tracker for the diagnostics/test-quality follow-up in #882 (named-chain error attribution + real-path tests + consolidating the types into _hooks.py). Will close once #882 lands.

  5. added a commit that references this issue on Jun 7, 2026
    3859131
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions