Python: agent-hooks interception contract as a first-class experimental core feature

[MohammadHaroonAbuomar]

Motivation & Context

Runtime controls for agents (policy engines, approval flows, information-flow checks, budget guards, audit pipelines) currently require one adapter per framework, and no framework defines what happens when a guardrail callback fails or lets a control author verify "supported" claims. AGENT-HOOKS-0.1 is a framework-neutral interception contract addressing this: eight interception points, a three-verdict model (allow / deny with liftable approval / transform), fail-closed host obligations, payload-free audit records, and a conformance test kit.

PR #7444 proposed this as an external adapter package. Maintainer feedback asked for a first-class experimental feature in core instead, with a single public factory, private middleware, an opt-in extra, and corrections to transform write-back, content preservation, and streaming semantics. This PR supersedes #7444 and implements exactly that design.

Description & Review Guide

• What are the major changes?
  • New agent_framework/_agent_hooks.py: one public factory, agent_hooks_middleware(...), returning a private agent/chat/function middleware trio (one object per middleware category, per categorize_middleware()). Partial installs and stacked trios fail closed with explicit errors, so a caller cannot accidentally install part of the control contract.
  • All eight interception points mapped to native seams: input/output at the agent seam, pre/post_model_call at the chat seam, pre/post_tool_call at the function seam, agent_startup/agent_shutdown bracketing each run. Transforms write back into the native contexts (messages, arguments, results) as Content objects; an unappliable transform raises rather than proceeding untransformed.
  • Fail-closed enforcement: MiddlewareTermination short-circuits are guarded at every seam (a substituted result passes the relevant interception point before egress); enforcement-layer failures halt the run; interceptor crashes surface as host_error denies.
  • Streaming is fully buffered (spec buffered_output semantics): no update egresses before the post_model_call/output verdicts; a deny at pull time releases zero updates; run state stays active across lazy pulls (ResponseStream.from_awaitable + result/cleanup hooks) with cleanup on every exit path.
  • Session scoping: per-run by default, or host-owned via emitter/builder parameters for one audit session spanning multiple runs.
  • agent-hooks-sdk is an opt-in agent-hooks extra (not in all), lazy-imported per the _mcp.py pattern; core imports cleanly without it. ExperimentalFeature.AGENT_HOOKS + @experimental, lazy root export, typing surface, PACKAGE_STATUS.md entry.
• What is the impact of these changes? No behavior change for anyone not calling the factory. New optional extra; no new required dependencies. 55 new tests built on the real Agent/mock-client flows (deny-before-execution, transform write-back, rich-content preservation, complete streaming ordering, error cleanup, concurrency isolation, nested agents, importability without the SDK). Full core suite, ruff, strict pyright, and uv lock --check pass locally.
• What do you want reviewers to focus on? The MiddlewareTermination guarding at the four seams; the buffered-streaming trade-off (callers get the stream API but updates arrive only after the output verdict — the only fully fail-closed option); tool-seam deny semantics (policy deny returns a reason-only error payload and the loop continues; host_error:* halts the run); and the sibling/stacking verification approach.

Known limitation to resolve before merge: agent-hooks-sdk on PyPI currently ships a linux-x86_64 wheel only, so uv sync --all-extras builds it from sdist elsewhere (macOS/Windows wheels are being published; will update this PR when live).

Related Issue

Supersedes #7444 (external-adapter draft, closed in favor of this first-class design per maintainer feedback).

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change.

Behavior change note

A bare middleware object passed to an agent constructor or assigned to the middleware attribute was previously ignored by run() (any non-sequence collapsed to no middleware); it now executes, matching the per-run middleware= parameter semantics.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework
_agent_hooks.py	748	150	79%	266, 303, 306–309, 311–322, 325–326, 332–333, 360, 364, 397, 399, 407–408, 414, 419, 462, 480–481, 555, 564–565, 571–572, 579, 583, 594–595, 598–599, 603, 615–616, 619, 622, 632–634, 636–637, 643, 650–658, 661–662, 669–672, 674–675, 700, 704, 732–738, 741–743, 767–774, 776–777, 796, 798, 807, 809–814, 824, 835–838, 854, 865–874, 994–995, 1049–1050, 1099, 1113–1114, 1142–1143, 1158, 1160, 1172–1177, 1245–1246, 1291, 1352, 1375, 1386, 1391, 1401, 1404–1408, 1429
_agents.py	453	45	90%	565, 577, 632, 1170, 1221, 1303–1307, 1406, 1436, 1473, 1565, 1593, 1606, 1658, 1660, 1669–1674, 1679, 1681, 1687–1688, 1695, 1697–1698, 1706–1707, 1710–1712, 1722–1727, 1731, 1736, 1738
_clients.py	143	12	91%	325, 376, 539–542, 992, 994–995, 997–999
_feature_stage.py	190	10	94%	110, 149, 165, 220, 231, 252, 290, 329, 379, 407
_middleware.py	440	16	96%	377, 743, 750–751, 933, 1004, 1022, 1024, 1157, 1160, 1187, 1189, 1325, 1329, 1516, 1592
_serialization.py	176	12	93%	356–357, 562, 572, 637, 640, 683–684, 688–689, 691, 693
_sessions.py	944	57	93%	163, 175–176, 213, 224, 238, 262, 307, 312, 314, 324, 356, 368, 378, 487, 556–557, 1270–1274, 1289, 1319, 1356–1357, 1371, 1373, 1392, 1394, 1477, 1517, 1594, 1598, 1608, 1825, 1858–1859, 1864, 1879, 1957–1958, 1960, 2044, 2061, 2140, 2213, 2242, 2261, 2264, 2272–2273, 2285–2286, 2298, 2308, 2338
_tools.py	1376	82	94%	231–232, 409, 411, 424, 449–451, 459, 477, 491, 498, 505, 528, 530, 537, 545, 680, 714–716, 719–721, 723, 729, 780–782, 807, 833, 837, 875–877, 881, 1054, 1066, 1073–1076, 1097, 1105, 1119–1121, 1491, 1574, 1624, 1684–1685, 1742, 1789, 1796–1797, 1887, 1949–1950, 1980, 2076, 2090, 2093, 2106, 2109, 2132, 2139, 2148, 2152, 2177, 2211, 2279, 2308–2309, 2406, 2434, 2474, 2477, 2534, 2687, 2776, 3270
_types.py	1291	99	92%	63, 73, 127, 136, 155, 157, 161, 165, 167, 169, 171, 189, 193, 219, 241, 246, 251, 255, 285, 711–712, 893–894, 1352, 1427, 1462, 1482, 1492, 1686–1688, 1973–1978, 2003, 2058, 2063, 2073, 2081, 2088–2092, 2110, 2183, 2196, 2201, 2314, 2337, 2598, 2622, 2721, 2902–2903, 3005, 3288, 3341, 3360, 3399, 3410, 3412–3416, 3418, 3421–3429, 3439, 3604, 3611, 3615–3617, 3762, 3767, 3772, 3777, 3781, 3867–3869, 3898, 3986–3990
observability.py	1029	79	92%	448, 450–451, 454, 457, 460–461, 466–467, 473–474, 480–481, 488, 490–491, 494, 497, 500–501, 506–507, 513–514, 520–521, 528, 705–706, 916, 920–922, 924, 932–933, 937, 981, 983, 994–996, 998–1000, 1004, 1012, 1136–1137, 1372, 1659–1660, 1923, 1966–1967, 2156, 2384–2385, 2389, 2429–2430, 2434, 2475–2478, 2519–2520, 2671, 2674, 2686, 2703, 2707–2708, 2711, 2717, 2837, 3058, 3060
packages/core/agent_framework/_harness
_agent.py	132	4	96%	202, 625–626, 628
packages/foundry/agent_framework_foundry
_agent.py	268	34	87%	124, 127, 251, 256, 265, 369, 477–478, 502, 505, 516–528, 532–533, 731–732, 735, 761, 771, 793, 881, 886, 890
TOTAL	45645	4251	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9259	34 💤	0 ❌	0 🔥	2m 22s ⏱️

[Copilot]

Pull request overview

Adds an experimental, first-class implementation of the AGENT-HOOKS-0.1 interception/enforcement contract to the Python core package (agent-framework-core), including an opt-in extra for the SDK dependency and a comprehensive test suite validating fail-closed behavior across agent/chat/tool seams (including buffered streaming).

Changes:

• Introduces agent_framework/_agent_hooks.py with the public agent_hooks_middleware(...) factory that returns an agent/chat/function middleware trio implementing all eight interception points and fail-closed semantics.
• Adds the opt-in agent-hooks extra (agent-hooks-sdk>=0.1.0a4,<0.2) and updates exports + experimental feature registration/documentation.
• Adds extensive unit tests covering deny/transform semantics, streaming buffering, short-circuit guarding, partial install detection, and optional-dependency importability.

Show a summary per file

File	Description
python/uv.lock	Adds the agent-hooks extra lock entries and locks agent-hooks-sdk 0.1.0a4.
python/packages/core/tests/core/test_agent_hooks.py	New test suite for agent-hooks enforcement and semantics across seams (incl. streaming).
python/packages/core/pyrightconfig.dependency.json	Excludes the new module from dependency-bound pyright checking.
python/packages/core/pyproject.toml	Adds agent-hooks optional dependency extra (explicitly not part of all).
python/packages/core/agent_framework/_feature_stage.py	Registers ExperimentalFeature.AGENT_HOOKS.
python/packages/core/agent_framework/_agent_hooks.py	Implements the enforcement middleware trio + projections/write-back + buffering semantics.
python/packages/core/agent_framework/init.pyi	Adds typing export for agent_hooks_middleware.
python/packages/core/agent_framework/init.py	Adds lazy runtime export for agent_hooks_middleware.
python/PACKAGE_STATUS.md	Documents the new experimental feature and its opt-in extra.

Review details

• Files reviewed: 8/9 changed files
• Comments generated: 2
• Review effort level: Lite

[moonbox3]

Have a look at the failing CI/CD (code quality checks) too, please. Thanks.

[moonbox3]

I think there's one streaming-only gap left in the retry scenario. On the non-streaming side call_next() runs inside with gate: (_agent_hooks.py:1020), but here it runs bare and the gate only gets entered later, inside _consume (:1131). So when a retry middleware drains attempt 1 with get_final_response() and throws away a response that actually succeeded, all of that draining happens with no gate active: attempt 1's exchange is persisted on the spot, before any verdict exists, and a later deny only drops attempt 2's deferred work. I reproduced this at the current head of the PR. The new retry tests don't catch it because _FlakyOnceClient fails attempt 1, so there's nothing to persist. Could we wrap call_next() in the gate here too (attempt identities are already accepted owners, so in-pipeline consumption would just defer), and add a streaming test where the discarded attempt succeeds?

[MohammadHaroonAbuomar]

Confirmed and fixed in 84671f1 — reproduced at head exactly as you described, and your read of why the retry tests missed it was right (the flaky client failed attempt 1, so there was nothing to persist). call_next() now runs inside the gate on the streaming seam too, mirroring the non-streaming path; drained attempts defer under their adopted identities, deny drops every attempt's work, and the probe battery also confirmed the nastier sibling (middleware raising after the drain) strands the pending persists unexecuted rather than leaking them. New tests: drained-and-discarded attempt under deny and allow in both stream modes (the streaming deny variant fails with the wrap reverted), plus a sub-agent tool invoked inside a drained attempt to pin that the tool-seam suspension still persists nested runs inline under the now-active gate. A probe also confirmed the non-streaming seam was already covered rather than assuming it.

[moonbox3]

Small docstring thing: this says binding is only reachable through the claim ticket, but the chat seam binds directly without one (_agent_hooks.py:1208). What's actually true at both sites is that every bind comes from a run inside the covered pipeline. Since this sentence is the whole argument for why accumulating owners is safe, it's worth saying it that way so it covers both paths, IMO.

[MohammadHaroonAbuomar]

Agreed — reworded in 84671f1 to state the invariant that actually holds at both sites: every bind comes from a run inside the covered pipeline; the agent seam binds through the instance-keyed claim ticket, the chat seam binds at gate creation to the run it executes in.