[FEAT] Add deterministic pre-action authorization at the tool-call hook level

[uchibeke]

Is your feature request related to a problem? Please describe.

VoltAgent's guardrail system validates content but doesn't deterministically authorize tool execution before it happens. With MCP servers proliferating, agents face silent injection risks where a poisoned prompt triggers unintended tool calls. The Open Agent Protocol (OAP) provides a before_tool_call hook that checks every execution against a declarative policy - agent identity, capability boundaries, and rate limits enforced at the framework level, not prompt level. Given VoltAgent's existing lifecycle hooks and Zod-typed tools, adding OAP support would be a minimal wrapper that unlocks enterprise security compliance. Reference implementation: https://github.com/aporthq/aport-agent-guardrails - DOI: 10.5281/zenodo.18901596

Describe alternatives you've considered

No response

Additional context

No response

Describe the thing to improve

Provide an option which when set wraps tool.execute() with before_tool_call hook that validates against a Local (Not external API call passport and policy) or Hosted pre-action auth (~50ms latency) before execution; adds passport context (agent identity + capabilities) to every tool call.

If this is something that is aligned with the roadmap, happy to open a contained PR for your review.

[The-Nexus-Guard]

The pre-action authorization pattern aligns with something we've been shipping in production on AIP — cryptographic agent identity that gates tool execution based on verifiable trust scores rather than prompt-level controls.

Two specific points where AIP could complement the OAP approach described here:

1. Identity foundation for the passport context.
The "agent identity + capabilities" passport mentioned here needs a cryptographic root. AIP provides this: each agent gets a did:aip identifier backed by Ed25519 key pairs, with a trust score (PDR — Promise-Delivery Ratio) computed from observed behavior. The before_tool_call hook could verify the agent's identity and its current trust score before authorizing execution.

from aip_identity import verify_identity, get_trust_score

def before_tool_call(agent_did, tool_name, params):
    # Verify the agent is who they claim to be (Ed25519 signature check)
    if not verify_identity(agent_did):
        raise AuthError("Agent identity verification failed")
    
    # Check behavioral trust score
    trust = get_trust_score(agent_did)
    if trust.pdr_score < 0.5:
        raise AuthError(f"Trust score {trust.pdr_score} below threshold")
    
    # Check capability scope
    if tool_name not in agent_capabilities[agent_did]:
        raise AuthError(f"Tool {tool_name} not in agent scope")

2. Cross-framework trust portability.
The hardest part of agent authorization isn't the hook itself — it's deciding who to trust across framework boundaries. AIP's trust graph currently has 22 registered agents with mutual vouching and cross-protocol verification (we just completed a 4-engine interop test with Kanoniv, APS, and Network-AI). A VoltAgent agent with an AIP identity would be verifiable by any framework in the trust network, not just VoltAgent's own guardrails.

The ~50ms latency constraint for hosted auth is achievable — AIP's /trust-path endpoint returns composite trust scores, and the middleware module handles request signing and peer verification.

Happy to help scope this if it's of interest. The cryptographic identity layer would be a clean addition to VoltAgent's existing lifecycle hooks.

[uchibeke]

The pre-action authorization pattern aligns with something we've been shipping in production on AIP — cryptographic agent identity that gates tool execution based on verifiable trust scores rather than prompt-level controls.

Two specific points where AIP could complement the OAP approach described here:

1. Identity foundation for the passport context. The "agent identity + capabilities" passport mentioned here needs a cryptographic root. AIP provides this: each agent gets a did:aip identifier backed by Ed25519 key pairs, with a trust score (PDR — Promise-Delivery Ratio) computed from observed behavior. The before_tool_call hook could verify the agent's identity and its current trust score before authorizing execution.

from aip_identity import verify_identity, get_trust_score

def before_tool_call(agent_did, tool_name, params):
# Verify the agent is who they claim to be (Ed25519 signature check)
if not verify_identity(agent_did):
raise AuthError("Agent identity verification failed")

# Check behavioral trust score
trust = get_trust_score(agent_did)
if trust.pdr_score < 0.5:
    raise AuthError(f"Trust score {trust.pdr_score} below threshold")

# Check capability scope
if tool_name not in agent_capabilities[agent_did]:
    raise AuthError(f"Tool {tool_name} not in agent scope")

2. Cross-framework trust portability. The hardest part of agent authorization isn't the hook itself — it's deciding who to trust across framework boundaries. AIP's trust graph currently has 22 registered agents with mutual vouching and cross-protocol verification (we just completed a 4-engine interop test with Kanoniv, APS, and Network-AI). A VoltAgent agent with an AIP identity would be verifiable by any framework in the trust network, not just VoltAgent's own guardrails.

The ~50ms latency constraint for hosted auth is achievable — AIP's /trust-path endpoint returns composite trust scores, and the middleware module handles request signing and peer verification.

Happy to help scope this if it's of interest. The cryptographic identity layer would be a clean addition to VoltAgent's existing lifecycle hooks.

Do you mind doing a PR? Goal will be for it to be decoupled from any specific guardrail implementation and:

• Allow people to implement their own guardrail or
• Use any provider/implementation like APort or AIP or
• Skip using guardrails completely so everything works like it would work without these changes

@omeraplak and @necatiozmen, what do you think?

[The-Nexus-Guard]

Absolutely — happy to do the PR.

Your constraints are exactly right. The interface should be:

1. Provider-agnostic guardrail hooks — before_tool_call, after_tool_call, on_delegation lifecycle hooks that accept a pluggable guardrail provider
2. Provider interface — a clean abstract class/protocol that AIP, APort, or any custom implementation can implement
3. Optional by default — no guardrail provider configured = existing behavior unchanged

I'd propose something like:

// Abstract guardrail provider interface
interface GuardrailProvider {
  // Called before tool execution — return permit/deny/review
  beforeToolCall(context: ToolCallContext): Promise<GuardrailDecision>;
  
  // Called after tool execution — for audit/logging
  afterToolCall(context: ToolCallContext, result: ToolResult): Promise<void>;
  
  // Optional: validate agent identity at registration
  validateIdentity?(agentId: string): Promise<IdentityResult>;
}

// Users configure in agent setup
const agent = new Agent({
  guardrail: new AIPGuardrailProvider({ threshold: 0.5 }),
  // or: guardrail: new APortProvider({ ... }),
  // or: omit entirely for no guardrails
});

Timeline: I can have a draft PR with the provider interface + a reference AIP implementation within a few days. The interface design is the important part — once that's solid, other providers can plug in trivially.

Questions before I start:

1. Is VoltAgent TypeScript-only, or is there a Python SDK too? (AIP is Python-native, so I'd write the AIP provider as a separate package that implements the TypeScript interface)
2. Any preference on where the hooks live in the existing architecture? I'll look at the codebase, but if there's a preferred pattern for lifecycle plugins, that'd save iteration.
3. Should the guardrail decision be able to modify the tool call (e.g., narrow parameters), or is it strictly permit/deny?

@uchibeke @omeraplak @necatiozmen

[alxvasilevvv]

Pre-action authorization is something we handle at MEEET World — 707 agents with role-based task access.

Each agent class (Research Scientist, Earth Scientist, Security Analyst...) has different tool permissions. Could be useful reference.

Implementation

[techfind777]

Deterministic pre-action authorization is essential for production agents. We implemented a similar pattern with a policy engine that checks tool calls against a whitelist before execution.

Key design decisions we found important:

1. Sync vs async authorization — sync blocks the agent loop (safer but slower), async requires rollback capability
2. Granularity — authorize at tool level vs parameter level (e.g., allow web_search but block searches for specific domains)
3. Caching — repeated identical tool calls should use cached authorization decisions

For anyone building this pattern, I documented our approach to agent security and authorization: https://aiagenttools.gumroad.com/l/avdtrl

Would love to see this become a first-class framework feature rather than something every team builds from scratch.

[FransDevelopment]

The before_tool_call authorization hook is the right pattern. One piece that could strengthen the "passport context" @uchibeke described: verifying which runtime issued the agent, not just the agent's own identity.

@The-Nexus-Guard's AIP provides agent-level identity and trust scoring (did:aip, PDR scores). The complementary layer is runtime-level identity: is the runtime that created this agent a known, registered entity?

The Open Agent Trust Registry (OATR) handles this. Agent runtimes register Ed25519 public keys. The runtime issues a signed JWT attestation (agent-attestation+jwt) for each agent it deploys. The before_tool_call hook verifies the attestation before execution. Verification is local (no external API call, under 1ms), which meets the latency constraint discussed in this thread.

How the hook would work:

// In before_tool_call:
import { OpenAgentTrustRegistry } from '@open-agent-trust/registry';

const registry = await OpenAgentTrustRegistry.load('https://mirror.example.com');

// Verify the agent's runtime attestation
const result = await registry.verifyToken(agent.attestation, toolTarget);

if (!result.valid) {
  return { authorized: false, reason: result.reason };
}

// result.claims.scope — what actions the runtime authorized
// result.issuer — which registered runtime issued this agent
// Then optionally check AIP trust score for behavioral layer

This composes with the approaches already discussed:

Layer	What it proves	Approach
Runtime identity (OATR)	Agent was issued by a known, non-revoked runtime	Ed25519 JWT attestation, local verification
Agent identity (AIP)	Agent has a verifiable DID and behavioral trust score	did:aip, PDR scoring
Policy authorization (OAP)	This specific tool call is allowed by policy	Declarative ALLOW/DENY rules

All three use Ed25519. The runtime attestation check adds ~0ms (local signature verification against a cached manifest). The Agent Identity Working Group has ratified three specs using these primitives, tested across 6 independent projects.

MIT licensed, 7 registered issuers, npm SDK: @open-agent-trust/registry.

[douglasborthwick-crypto]

The pre-action authorization gap @uchibeke described — checking agent capabilities before tool execution, not just content after — maps to a pattern we've been working on in the ERC-8183 ecosystem.

One input for the before_tool_call hook that's missing from the thread so far: wallet-state verification. Identity tells you who the agent is. Wallet state tells you what the agent holds — and that's often the better signal for authorization decisions.

InsumerAPI provides a signed trust profile — up to 39 checks across 32 chains (21 EVM + Solana + XRPL), covering stablecoins, governance tokens, NFTs, and native balances. Returned as an ECDSA-signed payload, verifiable offline via JWKS. The profile answers: is this wallet capitalized? Does it hold governance tokens (skin in the game)? Does it hold specific NFTs (membership/credential)?

For the GuardrailProvider interface, a TrustScoreGuardrailProvider could check the trust profile in before_tool_call and gate execution based on wallet state — e.g., only allow high-value tool calls from wallets with verified stablecoin holdings. The 30-minute TTL means you cache one call and gate multiple tool executions against it.

Happy to sketch the provider implementation if there's interest. Free API keys: POST https://api.insumermodel.com/v1/keys/create with {"email":"...","appName":"...","tier":"free"}.