[FEATURE]:Governance middleware hook for tool call authorization

[nagasatish007]

Feature Area

Agent capabilities

Is your feature request related to a an existing bug? Please link it here.

N/A

Describe the solution you'd like

Problem

CrewAI agents execute tools autonomously during crew runs. In production deployments, teams need governance controls:

• Which tools each agent is authorized to use (beyond just assigning tools)
• Cost tracking per agent across a crew run
• Audit trail for compliance (who called what, when, why)
• Ability to block specific tool calls based on runtime context (e.g., data sensitivity, time of day, budget remaining)

Currently, the only way to enforce this is by wrapping each tool's _run method individually, which doesn't compose well across crews.

Proposal

Add an optional governance hook that runs before each tool execution:

from crewai import Crew

def on_tool_call(agent, tool_name, tool_input, context):
    """Called before every tool execution. Raise to block."""
    if tool_name == "customer_export" and agent.role != "Admin":
        raise ToolBlockedError("customer_export requires Admin role")
    return True  # allow

crew = Crew(
    agents=[researcher, writer],
    on_tool_call=on_tool_call  # optional hook
)



This keeps governance decoupled from tool implementation — add/remove governance by changing the crew config, not every tool.

Working Example
I've built a working CrewAI + governance integration that demonstrates this pattern:

https://github.com/agentguard-ai/tealtiger/tree/main/examples/crewai-governance

It shows:

Policy-based tool authorization (allow/deny per tool per agent)
Per-agent cost tracking with CostTracker
A blocked customer_export tool call with clear error message
Works offline with deterministic demo mode (no API keys needed)
Uses TealTiger (open-source, Apache 2.0) for the governance engine, but the hook pattern would work with any policy engine.

Why this matters
OWASP's Agentic Top 10 identifies tool misuse (ASI-02) and access control failures (ASI-03) as top risks. A standard governance hook would let the CrewAI community build reusable authorization patterns without modifying individual tools.

Happy to submit a PR if a governance hook pattern is welcome.

### Describe alternatives you've considered

1. Wrapping each tool's _run method with governance logic — works but requires modifying every tool individually and doesn't compose across crews.

2. Subclassing Agent to override tool execution — tightly couples governance to a specific agent, breaks when switching agent types.

3. Post-hoc log analysis — only detects violations after they happen, doesn't prevent unauthorized actions.

A crew-level hook is preferred because it's non-invasive, composable, and works across all agents/tools without modification.


### Additional context

Working example with full source code: https://github.com/agentguard-ai/tealtiger/tree/main/examples/crewai-governance

This demonstrates:
- PolicyBuilder with allow/deny rules per tool
- governed_tool_call() wrapper pattern
- Per-agent cost tracking
- Blocked customer_export tool with clear error

OWASP Agentic Top 10 identifies tool misuse (ASI-02) and access control failures (ASI-03) as top risks for agentic applications.

Happy to submit a PR implementing this if the pattern is welcome.


### Willingness to Contribute

Yes, I'd be happy to submit a pull request

[Jairooh]

The governance pattern you're proposing is sound for CrewAI's architecture and addresses a genuine production need. As you scale this pattern, teams typically need real-time cost anomaly detection and risk scoring alongside runtime authorization. AgentShield already provides those aspects for CrewAI if you want to evaluate production-grade governance systems.

[rpelevin]

A crew-level on_tool_call hook is the right place to decouple governance from individual tool implementations.

One API question I would settle early: should the hook return only allow/block, or should it return a decision object that can be persisted with the run?

For production crews, I would expect the hook to be able to emit:

• agent role/id;
• tool name;
• input hash;
• target/resource;
• policy rule;
• route: allow, revise, human_review, or stop;
• reason;
• cost/risk metadata;
• timestamp and expiry if approval is time-bound.

That makes the governance hook useful for both runtime blocking and post-run audit without wrapping every tool.

Concrete receipt shape:

https://github.com/neurarelay/relay-action-card/blob/main/docs/decision-receipt-standard.md

No CrewAI integration claim. Sharing as a possible fixture shape for the middleware hook contract.

[nagasatish007]

Great point @rpelevin. A structured decision object is exactly what we've implemented in TealTiger's evidence contract (TEEC). It includes agent identity, tool name, input hash, policy rule, action (allow/deny/require_approval), reason, cost metadata, and cryptographic timestamp. Happy to align the hook's return type with this shape if the CrewAI team is open to it.

[rpelevin]

That sounds like the right convergence.

The part I would keep explicit in the hook contract is not only the evidence fields, but the decision validity state: route/action, expiry, supersession, and whether the external state must be revalidated before resume.

A small neutral core could be enough for CrewAI: agent, tool, input hash, policy rule, route/action, reason, cost/risk metadata, timestamp, expiry/supersession. TEEC, Neura-style receipts, or other implementations could then extend that shape without forcing one vendor object into the framework.

The key question for the CrewAI contract is whether the hook should return a portable decision object by default, rather than only allow/block.

[nagasatish007]

Agreed — a portable, vendor-neutral decision core is the right approach for CrewAI. The minimal shape you outlined (agent, tool, input_hash, policy_rule, route, reason, cost/risk, timestamp, expiry/supersession) maps cleanly to what we've implemented in TEEC.

The three additions I'd formalize:

expires_at — decision TTL (defaults to DENY on expiry)
supersedes — explicit override chain for policy-change scenarios
revalidate_if — conditions requiring re-evaluation before resume
Happy to co-draft a minimal GovernanceDecision type for the PR that any engine can implement. Keep it framework-owned (not vendor-owned) so CrewAI stays neutral.

[nagasatish007]

Great convergence here. A few notes:

@msaleme — Built the AutoGen adapter using exactly this pattern (ToolGuard + register_reply + audit subclass). Will share when ready. Also interested in running your 470-test harness against TealTiger-protected agents as a benchmark — open to that?

@vgudur-dev — TealMemory already implements provenance-tagged memory governance with transitive trust propagation (the taxonomy from OWASP GenAI Top 10 PR #69). The stack you described (memory integrity → governance hooks → audit trail) is exactly our architecture. Would be good to align Agent Memory Guard's YAML policy format with TealTiger's policy DSL for interoperability.

@chopmob-cloud — The content-addressed action_ref with JCS canonicalization is a clean addition. We use SHA-256 input hashing in TEEC but haven't formalized canonicalization. Will look at your IETF draft.

[vaaraio]

On the open API question (return allow/block, or a decision object): return a decision object, and make it the same shape you persist.

The split that has held up for us: a decision record written before the side effect (the verdict, the rule that fired, a risk basis, the hashed input scope) paired with an outcome record written after (executed, refused, or errored, plus an output commitment). The pair is what an auditor needs. A bare allow/block cannot answer "what happened after you allowed it."

Two things are worth deciding early because they are hard to retrofit:

• Sign the records and canonicalize them (JCS), so the decision object can be checked by someone who does not trust the process that produced it. An unsigned decision object is just a log line.
• Pin the verifier contract, not only the field list. Anyone can emit a receipt; the value is that an independent party can verify it.

This is also being standardized at the MCP protocol layer rather than per-framework, which is likely where the portable, vendor-neutral core this thread keeps reaching for belongs: modelcontextprotocol/modelcontextprotocol#2828 (server-side signed execution record). A CrewAI on_tool_call hook would be one emitter of that record shape.

For CrewAI specifically there is a working Apache-2.0 implementation (VaaraCrewGovernance, task-level and tool-level) in https://github.com/vaaraio/vaara , usable as a reference rather than a dependency.

[norika1207-lab]

One practical way to make this easier to evaluate is to turn the report into a small contract test around the runtime boundary, not only the user-facing symptom.

For governance middleware hook for tool call authorization, I would check three things: first, the failing input is preserved as a minimal fixture; second, the SDK emits the same observable event/result shape before and after the fix except for the intended change; third, the trace or serialized session contains enough metadata to explain what happened after a resume or retry.

The part that matters for agent systems is durability: if a tool call, memory write, handoff, or structured-output step fails, downstream code should not have to infer state from natural-language output. A focused regression test around that boundary would make the issue much easier to close with confidence.

[nagasatish007]

@norika1207-lab — this is a sharp framing. The three-part contract test you're describing (minimal fixture preservation, observable shape invariance pre/post fix, trace metadata sufficient for resume/retry reasoning) maps directly to what we've been building in TealTiger's TEEC (Typed Evidence & Evidence Contract).

A few things we've implemented that directly address your points:

Minimal fixture preservation: TealTiger's policy test harness runs governance assertions against deterministic fixtures — no API keys, no live calls, just the decision boundary. Each fixture captures the input, the policy rule that fired, and the expected decision. That fixture is also the regression test.

Observable shape invariance: TEEC v2.1 (shipping in v1.4) adds execution_outcome, stop_reason, and retry_posture fields specifically so the shape is consistent before and after a fix. The receipt before a retry and after a retry are structurally identical — only the outcome fields differ.

Durability metadata: The receipt includes tools_denied, side_effects.possible, side_effects.confirmed, and revalidate_if — exactly the fields needed to answer "is it safe to retry?" without inferring state from natural language.

Your point about durability is the one most frameworks get wrong. A bare allow/block is stateless — downstream code has no way to reconstruct what happened at the governance boundary. The decision object needs to be the source of truth, not the logs.

We're actively designing the crewai-tealtiger adapter with this contract in mind — would love to have your input on the fixture format and test harness design. If you're interested, there's an open discussion in the TealTiger community: https://github.com/orgs/agentguard-ai/discussions — happy to open a specific thread on the governance hook contract test spec if that's useful.

[nagasatish007]

@chopmob-cloud — the two-artifact split with a hash link between them is exactly the right architecture, and the payment-bearing workflow context makes the stakes concrete in a way that's hard to argue with.

A few points of convergence with what we're building in TEEC v2.1:

On the two-artifact model: We've been converging on the same split. TEEC v2.1 separates the governance decision (pre-execution, deterministic, policy-evaluated) from the execution outcome (post-execution, execution_outcome enum: EXECUTED / QUEUED / BLOCKED / PARTIAL). Your prev_hash back-link pattern is cleaner than what we currently have — we store a receipt_id reference but haven't formalized the hash chain between the two records. That's worth adopting directly.

On JCS canonicalization: Agreed — we've been using SHA-256 input hashing but haven't enforced RFC 8785 canonicalization. Your production experience with JCS + Ed25519 signatures is exactly the argument for formalizing it in TEEC v2.1. The validity.params_hash field in TEEC uses SHA-256 of canonicalized parameters — we should align with your JCS implementation.

On requires_revalidation: The treatment of policy version bump, agent identity rotation, and scope expansion as hard revalidation triggers (not carry-forwards) is the right default. We have revalidate_if as a field in TEEC v2.1 but haven't specified these exact trigger conditions. Your production list is a good starting set.

On Agent Trust Bench: Running the 166 adversarial profiles against a TealTiger-protected CrewAI crew would be genuinely useful — particularly the orchestrator injection and scope drift profiles, since those are the two attack vectors our crewai-tealtiger adapter needs to prove resistance to. Would you be open to that?

We're actively designing TEEC v2.1 and the crewai-tealtiger adapter right now. If you're interested in aligning the authorization record shape and verifier contract, there's an open discussion at https://github.com/orgs/agentguard-ai/discussions — happy to open a dedicated thread on the two-artifact chain spec where we can work through the field alignment in detail.

[redbotster]

The on_tool_call hook pattern you've outlined is exactly the right model. One thing worth considering at the policy layer: authorization decisions are most useful when the runtime context includes not just agent role and tool name, but also what credentials the agent is already holding. A tool that's safe for a read-only agent with no cloud credentials is a different risk level for an agent that's been given production AWS keys.

We ran into this at 1Claw building Vault, our HSM-backed credential broker for agents. The per-call cap and agent allowlist we enforce at the vault side complements a crew-level hook well: the hook decides if the agent is allowed to call the tool; the vault decides if the agent is allowed to use the credential the tool needs. Neither layer alone is sufficient for production. See docs.1claw.xyz if the credential-scoping side is useful context for the PR you're planning.