You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Server: support composing pre-validation hooks per tool #859
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:
run SDK compatibility hook
run adopter request normalization
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.
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.
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.
Activity
bokelley commentedon May 25, 2026
Triage
Classification: Feature request
Bucket(s): handlers, middleware
Status: ready-to-implement
What the experts said:
compose_pre_validation_hookshelper) is safer — leaves thePreValidationHookspublic type alias unchanged; internally normalize lists increate_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__).pre_validation_hooksacrossserve.py:601(Callable[..., Any]),a2a_server.py:184(dict[str, Any]), andmcp_tools.py:2438(precise typed signature) — fix annotation consistency as part of this work. Recommends exportingPreValidationHook(singular) alongside the existingPreValidationHooksalias.My take: Both experts converge on a non-breaking change — widen the per-tool value to
Callable | list[Callable]internally while also shipping acompose_pre_validation_hooks()helper for the "merge two separate hook dicts" use case. The annotation inconsistency and stalespec_compat.py:265docstring should be fixed in the same PR. PR authorization gate not yet met; posting implementation brief.Implementation scope:
src/adcp/server/spec_compat.py— addPreValidationHook = Callable[[str, dict[str, Any]], dict[str, Any]]type alias; updatePreValidationHooksvalue type toPreValidationHook | list[PreValidationHook]; remove/update line 264–266 ("only one callable per tool name" is now false); update_spec_compat_hooks_impldocstring.src/adcp/server/mcp_tools.py(~line 2087) — increate_tool_caller, normalize list-of-hooks to a single chained callable before theif 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) andsrc/adcp/server/serve.py(line 2317) — same normalization; all three.get(name)extraction sites must handlelistvalues; fixa2a_server.py:184annotation fromdict[str, Any]toPreValidationHooks.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 newsrc/adcp/server/_hooks.py(not inspec_compat.py, which is deprecated toward 6.0); re-export fromadcp.server.__init__.src/adcp/server/__init__.py— addPreValidationHook(singular) andcompose_pre_validation_hooksto__all__; fixserve()annotation on line 601 toPreValidationHooks.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 inINVALID_REQUESTmessage; (d) MCP + A2A call sites produce identical chaining behavior; (e)compose_pre_validation_hooksmerge semantics (two dicts with shared key produces a two-hook chain).dict[str, Callable]callers satisfy the widenedCallable | 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
bokelley commentedon Jun 6, 2026
The core of this — per-tool pre-validation hook composition — shipped in #860:
PreValidationHook,PreValidationHookChain,PreValidationHooks, andcompose_pre_validation_hooks()are live insrc/adcp/server/spec_compat.py, ordered chains are applied inmcp_tools.py, and they're threaded througha2a_server.pyandserve().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.fix(server): centralize pre-validation hooks and attribute chain fail…