Python: agent-framework-agent-hooks — middleware adapter for the AGENT-HOOKS-0.1 control contract

[MohammadHaroonAbuomar]

Problem

Controls for agentic workloads (policy engines, approval flows, information-flow checks, audit pipelines) are rebuilt per framework, and each framework answers differently whether a control can stop an action, what happens when a control crashes, and what evidence exists afterwards. AGENT-HOOKS-0.1 (https://github.com/responsibleai/agent-hooks) is a framework-neutral control contract: eight interception points, a three-verdict model (allow / deny with optional human-approval lift / transform), normative fail-closed host obligations, and a conformance kit that makes "supported" checkable (https://responsibleai.github.io/agent-hooks/).

What this adds

A self-contained workspace package, agent-framework-agent-hooks, following the layout of the existing integration packages. One factory wires the contract into the middleware pipeline:

agent = Agent(..., middleware=agent_hooks_middleware(interceptors=[policy], resolver=approvals))

Middleware mapping (full analysis in MAPPING.md)

Agent Framework seam	Interception point
AgentMiddleware	input / output (plus synthesized agent_startup / agent_shutdown per run)
ChatMiddleware	pre_model_call / post_model_call
FunctionMiddleware	pre_tool_call / post_tool_call (transform writes back into executed arguments)

All three tiers have native control semantics (call_next, MiddlewareTermination, result override), so blocking and transforming compose with the framework rather than fighting it. Deny anywhere raises MiddlewareTermination; adapter errors terminate the run (fail closed), never fall through.

Limitations (deliberate, documented in MAPPING.md)

• No framework lifecycle seam for session boundaries: agent_startup/agent_shutdown bracket one agent run (a session-scoped seam is the concrete upstream ask).
• Streaming runs enforce pre-action points only; post/output enforcement over streams needs a stream_result_hooks integration (natural follow-up).
• post_model_call tool-call extraction is best-effort across client result shapes.

Test evidence

5/5 pytest green against published agent-hooks-sdk 0.1.0a4: run-point sequencing, deny-blocks-tool with post-point suppression and session-trail closure, transform write-back proving execution sees the approved value, and no-op behavior outside a bracketed run. Ruff clean under the repository configuration.

Conformance

The contract ships a 47-vector conformance kit and a public claims registry; the reference policy runtime (https://github.com/responsibleai/agent-control-spec) passes 46/47 as an interceptor-side consumer. An Agent Framework host conformance claim would follow once the streaming and session seams land.

[MohammadHaroonAbuomar]

Review pass (self-review before sharing). Findings; fixes follow on the branch.

1. post_tool_call is skipped when the tool raises. AgentHooksFunctionMiddleware.process emits the post point only on the success path; a raising call_next propagates without post_tool_call (is_error: true). The contract brackets every completed invocation, success or error.
2. Raw context.result flows into the post_tool_call value. A non-JSON-serializable tool result would fail inside the emitter's marshalling, terminating the run with a crash-shaped error rather than a typed record; project the value defensively the way _arguments_to_dict does for arguments.