feat: add AgentFuse tool guardrail plugin

[MkaliezZ]

Context

The architecture review on PraisonAI #4023 directed vendor-specific lifecycle and guardrail integrations to PraisonAI-Plugins while retaining generic tool_call_id middleware plumbing in core.

Boundary

This optional plugin uses PraisonAI's public wrap_tool_call, ToolRequest, and ToolResponse APIs at the final middleware boundary before protected handler dispatch.

Semantics

• Allow: the existing handler chain runs normally.
• Block: returns a host-native ToolResponse with outcome=not_executed; the handler does not start.
• Guard failure: an unexpected exception from guard.evaluate(...) is caught by the adapter and also returns not_executed; the handler does not start.
• Handler failure after allow: remains owned by PraisonAI and is not converted into a policy block.
• Identity: reads the original tool_call_id from InvocationContext.metadata; missing identity fails closed without fabricating an ID.

Dependency

Optional extra:

praisonai-plugins[agentfuse] -> dhms-agentfuse==3.7.3

Validation

Clean Python 3.12.13 environment with praisonaiagents==1.6.167, praisonai-plugins==0.0.5, and dhms-agentfuse==3.7.3:

python -m pytest tests/test_agentfuse_tool_middleware.py
7 passed

python -m pytest
45 passed

ruff check src/praisonai_plugins/guardrails/agentfuse.py tests/test_agentfuse_tool_middleware.py
All checks passed!

ruff format --check src/praisonai_plugins/guardrails/agentfuse.py tests/test_agentfuse_tool_middleware.py
2 files already formatted

python -m build
Successfully built sdist and wheel

Observed protected-handler counts:

• sync allow: 1
• sync block: 0
• RuntimeGuard internal policy error: 0
• adapter-level evaluate exception: 0
• async block: 0
• missing identity: 0

Scope

Optional lifecycle/guardrail plugin only. It does not modify PraisonAI core, approval semantics, retries, or handler-failure ownership.

AgentFuse 3.7.3 is Experimental Public Beta. This draft does not imply PraisonAI endorsement, certification, or production-security guarantees.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: d6b1a918-e8d7-4805-b5b7-7efb019ba01a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[MervinPraison]

@copilot Do a thorough review of this PR. Read ALL existing reviewer comments above from Qodo, Coderabbit, and Gemini first — incorporate their findings.

Review areas:

1. Bloat check: Are changes minimal and focused? Any unnecessary code or scope creep?
2. Security: Any hardcoded secrets, unsafe eval/exec, missing input validation?
3. Performance: Any module-level heavy imports? Hot-path regressions?
4. Tests: Are tests included? Do they cover the changes adequately?
5. Backward compat: Any public API changes without deprecation?
6. Code quality: DRY violations, naming conventions, error handling?
7. Address reviewer feedback: If Qodo, Coderabbit, or Gemini flagged valid issues, include them in your review
8. Suggest specific improvements with code examples where possible

[MervinPraison]

@claude You are the FINAL architecture reviewer. If the branch is under MervinPraison/PraisonAI-Plugins (not a fork), you are able to make modifications to this branch and push directly. SCOPE: Focus ONLY on PraisonAI-Plugins (src/praisonai_plugins, tests). Do not expand into praisonaiagents or the monorepo unless the issue explicitly requires it. Read ALL comments above from Gemini, Qodo, CodeRabbit, and Copilot carefully before responding.

Phase 1: Review per AGENTS.md

1. Protocol-driven: check heavy implementations vs core SDK
2. Backward compatible: ensure zero feature regressions
3. Performance: no hot-path regressions (lazy imports, import-time <200ms)
4. SDK/product value: review whether the change genuinely adds value — correct plugin layering (lifecycle hooks/guardrails/sandbox backends here; agent tools belong in PraisonAI-Tools; core SDK in praisonaiagents). Reject scope creep; request changes or recommend closing if value is unclear

Phase 2: FIX Valid Issues
5. For any VALID bugs or architectural flaws found by Gemini, CodeRabbit, Qodo, Copilot, or any other reviewer: implement the fix
6. Push all code fixes directly to THIS branch (do NOT create a new PR)
7. Comment a summary of exact files modified and what you skipped

Phase 3: Final Verdict
8. If all issues are resolved, approve the PR / close the Issue
9. If blocking issues remain, request changes / leave clear action items

[praisonai-triage-agent]

Claude encountered an error —— View job

---

I'll analyze this and get back to you.