Python: Add HOL Guard middleware sample

[samsul hoque mondal (deathsamsul)]

Motivation & Context

This PR adds a HOL Guard FunctionMiddleware sample for protecting tool calls.

It provides a deterministic enforcement point before tool execution and fails closed when HOL Guard is unavailable or returns a non-allow decision.

This addresses the requirements described in issue #7833.

Description & Review Guide

• What are the major changes?

  • Add HOLGuardMiddleware sample.
  • Evaluate tool name and validated arguments before call_next().
  • Allow tool execution only when HOL Guard returns allow.
  • Fail closed for deny, review, unavailable, and error outcomes.
  • Add an optional offline fallback for local demonstration.
  • Add unit tests covering allow, deny, unavailable, and offline fallback behavior.

• What is the impact of these changes?

  • Adds a new Python middleware sample.
  • Adds unit tests.
  • No existing framework behavior is changed.

• What do you want reviewers to focus on?

  • The middleware's fail-closed behavior.
  • The point at which HOL Guard is invoked relative to tool execution.
  • The test coverage for allow and non-allow decisions.

Related Issue

Fixes #7833

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
• This is not a breaking change.

[Copilot]

Pull request overview

Adds a Python FunctionMiddleware sample intended to guard tool execution with HOL Guard.

Changes:

• Adds HOL Guard evaluation with fail-closed middleware behavior.
• Adds an offline demonstration fallback.
• Adds allow, deny, and unavailable-path tests.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
python/samples/02-agents/middleware/hol_guard_middleware.py	Implements the middleware and runnable sample.
python/tests/samples/agents/test_hol_guard_middleware.py	Tests guard decisions and tool execution behavior.

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[samsul hoque mondal (deathsamsul)]

/review
Eduard van Valkenburg (@eavanvalkenburg)
Giles Odigwe (@giles17)
Evan Mattson (@moonbox3)
Tao Chen (@TaoChenOSU)

[Michael Kantor (kantorcodes)]

HOL Guard maintainer clarification on the open contract question:

• hol-guard command test <command> --json is preview/inspection only. Its no_match result should not be described as a full HOL Guard policy approval; policy_evaluation is intentionally not_run on that path.
• release/3.0 now also exposes hol-guard policy evaluate-command <policy.yml> --command "<command>" --json, but that evaluates the explicit policy document passed to it. It is not a drop-in stand-in for the active harness/runtime policy.
• The authoritative enforcement path is still the supported HOL Guard runtime/harness integration, where Guard mediates the actual command/tool execution with the current runtime policy/approval context.

So for this sample I’d either keep command test but frame it strictly as pattern inspection (don’t call no_match a policy allow), or make a policy file an explicit sample input and use policy evaluate-command. I also would not ship offline_fallback=True as the default runnable path in an example described as fail-closed; keeping that opt-in for demo/dev avoids silently downgrading protection when Guard is unavailable.

Current parser source for the explicit policy command: https://github.com/hashgraph-online/hol-guard/blob/release/3.0/src/codex_plugin_scanner/guard/cli/commands_parser_policy.py

[Eduard van Valkenburg (eavanvalkenburg)]

Closing per the message on the issue.