Proposal: tool_execute_after as documented public hook point + reference implementation for code-level directive enforcement

[wgnrai]

Summary

We have built and tested a plugin-based enforcement mechanism that uses Agent Zero's tool_execute_after extension hook on the response tool to enforce behavioral directives at the code level. The mechanism is proven in our production environment with 168 passing tests and live telemetry (37 events, 0ms median latency overhead).

What we built

A pre-response verification gate plugin (_pre_response_verification_gate) that:

1. Intercepts the agent loop at tool_execute_after on the response tool (after execute() but before the break_loop check)
2. Checks the draft response for unverified claims (cross-turn referent contradictions, unsourced attachment claims, unfiled project artifacts)
3. If a check fires: sets response.break_loop = False and injects self.agent.hist_add_warning(message=...) with a directive to run a verification tool
4. The model sees the warning and calls the appropriate verification tool before re-attempting the response

This pattern was first proven by the delegation gate plugin (_delegation_gate) which uses the same mechanism to enforce delegation directives.

What we're proposing upstream

1. Document tool_execute_after as a public hook point -- it's currently used by plugins but not formally documented as an extension point in the plugin contract. The semantics are: fires after execute() completes, before break_loop check. The Response object is mutable at this point (passed by reference).

2. Reference implementation -- our gate demonstrates that plugin-based code-level enforcement of behavioral directives is feasible with zero framework core changes. This pattern could benefit other Agent Zero users who want to enforce quality gates (verification, delegation, safety) structurally rather than via prompt-only rules.

Evidence

• Plugin: _pre_response_verification_gate (168 tests, 0 failures)
• Precedent: _delegation_gate (same pattern, different enforcement class)
• Live telemetry: 37 events over ~4 hours, 51.4% fire rate, 0ms median latency, zero crashes
• Two documented production incidents that motivated the build (cross-turn contradiction + citation fabrication)

Technical details

• Hook point: extensions/python/tool_execute_after/_10_pre_response_gate.py
• Config: tri-state profile gating (always_gated / audit_only_gated / never_gated)
• Logging: plugin-local JSONL with 30-day rolling rotation
• No framework core files modified -- entirely plugin-layer