Add beforeApprove hook for agent capability approval

[brookyale0512]

Summary

• Adds a beforeApprove hook to AgentAuthOptions, called after approval/session validation and immediately before pending grants are activated.
• Passes the full set of capabilities being approved so applications can enforce the strongest proof required across multi-capability approvals.
• Preserves all-or-nothing approval behavior: if the hook throws, no pending grant is activated.

Motivation

Some deployments need app-specific proof-of-presence before activating an agent capability grant, such as fresh password re-authentication, WebAuthn confirmation, MFA, or policy checks against an external identity system. Today those deployments have to fork or replace the approval route, which means they lose the built-in Agent Auth approval lifecycle.

This hook keeps the core approval flow in Agent Auth while allowing applications to add deployment-specific checks at the final safe point before grant activation.

API

beforeApprove?: (ctx: BeforeApproveContext) => void | Promise<void>;

The hook succeeds by returning normally and aborts by throwing APIError or another error handled by the existing route error path. It does not return a boolean or decision object.

BeforeApproveContext includes:

• userId
• session
• capabilities[]
• deprecated first-capability convenience fields: capability, constraints
• parsed body
• original request

Test Plan

• pnpm fmt:check
• pnpm --filter @better-auth/agent-auth typecheck
• pnpm --filter @better-auth/agent-auth test
• pnpm --filter @better-auth/agent-auth build

All commands passed locally under Node 24.

[vercel]

@brookyale0512 is attempting to deploy a commit to the better-auth Team on Vercel.

A member of the Team first needs to authorize it.