feat(core): add agent tool authorization guard

Add an Agent-level toolGuard hook that can deny local tool execution before the tool runs. Denied calls reuse the existing ToolDeniedError path so tool error/end hooks still receive audit context.\n\nAdds behavior and type coverage for the new guard API.\n\nRelated to #1177.

Author: MaskerFather

packages/core/src/agent/agent.spec-d.ts

@@ -628,6 +628,32 @@ describe("Agent Type System", () => {
       expectTypeOf(hooks).toMatchTypeOf<AgentHooks>();
     });
 
+    it("should validate agent toolGuard option", () => {
+      const agentOptions: AgentOptions = {
+        name: "GuardedAgent",
+        instructions: "Test",
+        model: "openai/gpt-4o-mini",
+        toolGuard: async ({ agent, tool, args, context }) => {
+          expectTypeOf(agent).toMatchTypeOf<Agent>();
+          expectTypeOf(tool.name).toEqualTypeOf<string>();
+          expectTypeOf(args).toBeAny();
+          expectTypeOf(context).toMatchTypeOf<OperationContext>();
+          return { denied: true, reason: "read-only" };
+        },
+      };
+
+      expectTypeOf(agentOptions).toMatchTypeOf<AgentOptions>();
+
+      const booleanGuardOptions: AgentOptions = {
+        name: "BooleanGuardAgent",
+        instructions: "Test",
+        model: "openai/gpt-4o-mini",
+        toolGuard: () => true,
+      };
+
+      expectTypeOf(booleanGuardOptions).toMatchTypeOf<AgentOptions>();
+    });
+
     it("should allow sync and async hooks", () => {
       const syncHooks: AgentHooks = {
         onStart: () => {

packages/core/src/agent/agent.spec.ts

@@ -1489,6 +1489,77 @@ Use pandas and summarize findings.`.split("\n"),
       operationContext.traceContext.end("completed");
     });
 
+    it("blocks tool execution when toolGuard denies the tool", async () => {
+      const execute = vi.fn().mockResolvedValue("should-not-run");
+      const toolGuard = vi.fn().mockResolvedValue({
+        denied: true,
+        reason: "read-only agent",
+      });
+      const onToolError = vi.fn();
+      const onToolEnd = vi.fn();
+      const agent = new Agent({
+        name: "TestAgent",
+        instructions: "Test",
+        model: mockModel as any,
+        toolGuard,
+        hooks: createHooks({ onToolError, onToolEnd }),
+      });
+
+      const protectedTool = new Tool({
+        name: "delete-note",
+        description: "Deletes a note",
+        parameters: z.object({ id: z.string() }),
+        execute,
+      });
+
+      const operationContext = (agent as any).createOperationContext("input");
+      const executeFactory = (agent as any).createToolExecutionFactory(
+        operationContext,
+        agent.hooks,
+      );
+
+      const result = await executeFactory(protectedTool)({ id: "note-1" });
+
+      expect(execute).not.toHaveBeenCalled();
+      expect(toolGuard).toHaveBeenCalledWith(
+        expect.objectContaining({
+          agent,
+          tool: protectedTool,
+          args: { id: "note-1" },
+          context: operationContext,
+        }),
+      );
+      expect(result).toMatchObject({
+        error: true,
+        toolName: "delete-note",
+        code: "TOOL_FORBIDDEN",
+      });
+      expect(result.message).toContain("read-only agent");
+      expect(onToolError).toHaveBeenCalledTimes(1);
+      const toolErrorArgs = onToolError.mock.calls[0][0];
+      expect(toolErrorArgs.tool).toBe(protectedTool);
+      expect(toolErrorArgs.args).toEqual({ id: "note-1" });
+      expect(toolErrorArgs.originalError).toMatchObject({
+        code: "TOOL_FORBIDDEN",
+        message: "read-only agent",
+      });
+      expect(toolErrorArgs.error).toMatchObject({
+        message: "read-only agent",
+        stage: "tool_execution",
+      });
+
+      expect(onToolEnd).toHaveBeenCalledTimes(1);
+      const toolEndArgs = onToolEnd.mock.calls[0][0];
+      expect(toolEndArgs.tool).toBe(protectedTool);
+      expect(toolEndArgs.output).toBeUndefined();
+      expect(toolEndArgs.error).toMatchObject({
+        message: "read-only agent",
+        stage: "tool_execution",
+      });
+
+      operationContext.traceContext.end("completed");
+    });
+
     it("calls onToolError when a tool throws", async () => {
       const onToolError = vi.fn();
       const onToolEnd = vi.fn();

packages/core/src/agent/agent.ts

@@ -106,7 +106,12 @@ import {
   type EnqueueEvalScoringArgs,
   enqueueEvalScoring as enqueueEvalScoringHelper,
 } from "./eval";
-import type { AgentHooks, OnToolEndHookResult, OnToolErrorHookResult } from "./hooks";
+import type {
+  AgentHooks,
+  AgentToolGuard,
+  OnToolEndHookResult,
+  OnToolErrorHookResult,
+} from "./hooks";
 import { stripDanglingOpenAIReasoningFromModelMessages } from "./model-message-normalizer";
 import { AgentTraceContext, addModelAttributesToSpan } from "./open-telemetry/trace-context";
 import {
@@ -1044,6 +1049,7 @@ export class Agent {
   private readonly workspaceToolkitOptions: AgentOptions["workspaceToolkits"];
   private readonly workspaceSkillsPromptOption: AgentOptions["workspaceSkillsPrompt"];
   private readonly configuredHooks?: AgentHooks;
+  private readonly toolGuard?: AgentToolGuard;
   private readonly maxStepsConfigured: boolean;
   private defaultObservability?: VoltAgentObservability;
   private readonly toolManager: ToolManager;
@@ -1078,6 +1084,7 @@ export class Agent {
     this.workspaceToolkitOptions = options.workspaceToolkits;
     this.workspaceSkillsPromptOption = options.workspaceSkillsPrompt;
     this.configuredHooks = options.hooks;
+    this.toolGuard = options.toolGuard;
     this.maxStepsConfigured = options.maxSteps !== undefined;
     const globalWorkspace = AgentRegistry.getInstance().getGlobalWorkspace();
     const workspaceOption = options.workspace === undefined ? globalWorkspace : options.workspace;
@@ -6421,6 +6428,46 @@ export class Agent {
     return parseResult.data;
   }
 
+  private async assertToolGuardAllows(
+    tool: BaseTool | ProviderTool,
+    args: any,
+    oc: OperationContext,
+    options?: ToolExecuteOptions,
+  ): Promise<void> {
+    if (!this.toolGuard) {
+      return;
+    }
+
+    const result = await this.toolGuard({
+      agent: this,
+      tool: tool as any,
+      context: oc,
+      args,
+      options,
+    });
+
+    const denied =
+      result === false ||
+      (typeof result === "object" &&
+        result !== null &&
+        (result.denied === true || result.allowed === false));
+    if (!denied) {
+      return;
+    }
+
+    const reason =
+      typeof result === "object" && result !== null && typeof result.reason === "string"
+        ? result.reason
+        : "Tool execution denied by toolGuard.";
+
+    throw new ToolDeniedError({
+      toolName: tool.name,
+      message: reason,
+      code: "TOOL_FORBIDDEN",
+      httpStatus: 403,
+    });
+  }
+
   private createToolExecutionFactory(
     oc: OperationContext,
     hooks: AgentHooks,
@@ -6623,6 +6670,7 @@ export class Agent {
           try {
             await this.waitForSpeculativeInputGuardrail(oc);
             await oc.traceContext.withSpan(toolSpan, async () => {
+              await this.assertToolGuardAllows(tool, args, oc, executionOptions);
               await runToolStartHooks();
             });
 
@@ -6683,7 +6731,8 @@ export class Agent {
       return oc.traceContext.withSpan(toolSpan, async () => {
         try {
           await this.waitForSpeculativeInputGuardrail(oc);
-          // Call tool start hook - can throw ToolDeniedError
+          // Call tool guard and start hook - both can throw ToolDeniedError
+          await this.assertToolGuardAllows(tool, args, oc, executionOptions);
           await runToolStartHooks();
 
           // Execute tool with merged options
@@ -7242,6 +7291,7 @@ export class Agent {
           `Provider tool "${tool.name}" received arguments that do not match callTool input.`,
         );
       }
+      await this.assertToolGuardAllows(tool, callInput, oc, executionOptions);
       await hooks.onToolStart?.({
         agent: this,
         tool: tool as any,

packages/core/src/agent/hooks/index.ts

@@ -59,6 +59,19 @@ export interface OnToolStartHookArgs {
   options?: ToolExecuteOptions;
 }
 
+export interface ToolGuardArgs extends OnToolStartHookArgs {}
+
+export type ToolGuardResult =
+  | boolean
+  | {
+      allowed?: boolean;
+      denied?: boolean;
+      reason?: string;
+    }
+  | undefined;
+
+export type AgentToolGuard = (args: ToolGuardArgs) => Promise<ToolGuardResult> | ToolGuardResult;
+
 export interface OnToolEndHookArgs {
   agent: Agent;
   tool: AgentTool;

packages/core/src/agent/types.ts

@@ -55,7 +55,7 @@ import type {
   WorkspaceSkillsToolkitOptions,
 } from "../workspace";
 import type { ContextInput } from "./agent";
-import type { AgentHooks } from "./hooks";
+import type { AgentHooks, AgentToolGuard } from "./hooks";
 import type { AgentTraceContext } from "./open-telemetry/trace-context";
 
 // Re-export for backward compatibility
@@ -717,6 +717,11 @@ export type AgentOptions = {
 
   // Hooks
   hooks?: AgentHooks;
+  /**
+   * Optional per-tool authorization guard.
+   * Return `false`, `{ allowed: false }`, or `{ denied: true }` to block execution.
+   */
+  toolGuard?: AgentToolGuard;
 
   // Guardrails
   inputGuardrails?: InputGuardrail[];