feat(core): add execution validators

.changeset/execution-validators.md

@@ -0,0 +1,42 @@
+---
+"@voltagent/core": minor
+"@voltagent/server-core": patch
+---
+
+feat(core): add pre-execution validators for tools and workflows
+
+Agents and workflows can now define `executionValidators` that run before tool execution or
+workflow step execution. Validators can return `false` or `{ pass: false }` to block the run with
+an `ExecutionValidationError`, including a custom message, code, HTTP status, and metadata. They
+can run synchronously or asynchronously.
+
+```ts
+const agent = new Agent({
+  name: "Policy Controlled Assistant",
+  instructions: "You enforce tenant policy.",
+  model: "openai/gpt-4o",
+  tools: [updateRecordTool],
+  executionValidators: {
+    tools: [
+      async ({ toolName, operationContext }) => {
+        const tenant = operationContext?.requestHeaders?.["x-tenant-id"];
+        const allowed = await checkTenantToolAccess({ tenant, toolName });
+
+        if (toolName === "update_record" && !allowed) {
+          return {
+            pass: false,
+            message: "This tenant cannot update records.",
+            code: "TOOL_TENANT_DENIED",
+            httpStatus: 403,
+          };
+        }
+      },
+    ],
+  },
+});
+```
+
+Server-core direct tool and workflow handlers now preserve `ClientHTTPError` details so blocked
+executions can return the validator's status and code instead of a generic 500.
+
+Fixes #1213

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

@@ -1714,6 +1714,67 @@ Use pandas and summarize findings.`.split("\n"),
 
       operationContext.traceContext.end("completed");
     });
+
+    it("runs execution validators before tool start hooks and execution", async () => {
+      const validator = vi.fn(() => ({
+        pass: false as const,
+        message: "Destination is outside the allowed tenant",
+        code: "TENANT_POLICY_BLOCKED",
+        httpStatus: 412 as const,
+      }));
+      const onToolStart = vi.fn();
+      const executeTool = vi.fn().mockResolvedValue("should-not-run");
+      const agent = new Agent({
+        name: "TestAgent",
+        instructions: "Test",
+        model: mockModel as any,
+        hooks: createHooks({ onToolStart }),
+        executionValidators: {
+          tools: [validator],
+        },
+      });
+
+      const tool = new Tool({
+        name: "send-message",
+        description: "Send a message",
+        parameters: z.object({ destination: z.string() }),
+        execute: executeTool,
+      });
+
+      const operationContext = (agent as any).createOperationContext("input");
+      const executeFactory = (agent as any).createToolExecutionFactory(
+        operationContext,
+        agent.hooks,
+      );
+
+      const execute = executeFactory(tool);
+      const result = await execute({ destination: "external" });
+
+      expect(validator).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: "tool",
+          agent,
+          tool,
+          toolName: "send-message",
+          args: { destination: "external" },
+          operationContext,
+          timestamp: expect.any(Date),
+        }),
+      );
+      expect(onToolStart).not.toHaveBeenCalled();
+      expect(executeTool).not.toHaveBeenCalled();
+      expect(operationContext.abortController.signal.aborted).toBe(true);
+      expect(result).toMatchObject({
+        error: true,
+        name: "ExecutionValidationError",
+        message: "Destination is outside the allowed tenant",
+        code: "TENANT_POLICY_BLOCKED",
+        httpStatus: 412,
+        toolName: "send-message",
+      });
+
+      operationContext.traceContext.end("completed");
+    });
   });
 
   describe("Agent as Tool (toTool)", () => {

packages/core/src/agent/agent.ts

@@ -48,6 +48,11 @@ import {
   validateUIMessages,
 } from "ai";
 import { z } from "zod";
+import {
+  type AgentExecutionValidators,
+  type ToolExecutionValidationContext,
+  runExecutionValidators,
+} from "../execution-validation";
 import { LogEvents, LoggerProxy } from "../logger";
 import { ActionType, buildAgentLogMessage } from "../logger/message-builder";
 import { Memory } from "../memory";
@@ -97,6 +102,7 @@ import {
   createVoltAgentError,
   isBailError,
   isClientHTTPError,
+  isExecutionValidationError,
   isMiddlewareAbortError,
   isToolDeniedError,
   isVoltAgentError,
@@ -279,6 +285,20 @@ const firstDefined = <T>(...values: Array<T | null | undefined>): T | undefined
   return undefined;
 };
 
+const normalizeAgentExecutionValidators = (
+  validators?: AgentExecutionValidators,
+): AgentExecutionValidators | undefined => {
+  const tools = validators?.tools?.filter((validator) => typeof validator === "function") ?? [];
+  return tools.length > 0 ? { tools: [...tools] } : undefined;
+};
+
+const mergeAgentExecutionValidators = (
+  ...configs: Array<AgentExecutionValidators | undefined>
+): AgentExecutionValidators | undefined => {
+  const tools = configs.flatMap((config) => config?.tools ?? []);
+  return tools.length > 0 ? { tools } : undefined;
+};
+
 type OpenRouterUsageCost = {
   cost?: number;
   isByok?: boolean;
@@ -902,6 +922,9 @@ export interface BaseGenerationOptions<TProviderOptions extends ProviderOptions
   // Hooks (can override agent hooks)
   hooks?: AgentHooks;
 
+  // Execution validators (can add per-call validators)
+  executionValidators?: AgentExecutionValidators;
+
   // Guardrails (can override agent-level guardrails)
   inputGuardrails?: InputGuardrail[];
   outputGuardrails?: OutputGuardrail<any>[];
@@ -1004,6 +1027,7 @@ export class Agent {
   private readonly prompts?: PromptHelper;
   private readonly evalConfig?: AgentEvalConfig;
   private readonly feedbackOptions?: AgentFeedbackOptions | boolean;
+  private readonly executionValidators?: AgentExecutionValidators;
   private readonly inputGuardrails: NormalizedInputGuardrail[];
   private readonly outputGuardrails: NormalizedOutputGuardrail[];
   private readonly inputMiddlewares: NormalizedInputMiddleware[];
@@ -1048,6 +1072,7 @@ export class Agent {
     this.voltOpsClient = options.voltOpsClient;
     this.evalConfig = options.eval;
     this.feedbackOptions = options.feedback;
+    this.executionValidators = normalizeAgentExecutionValidators(options.executionValidators);
     this.inputGuardrails = normalizeInputGuardrailList(options.inputGuardrails || []);
     this.outputGuardrails = normalizeOutputGuardrailList(options.outputGuardrails || []);
     this.inputMiddlewares = normalizeInputMiddlewareList(options.inputMiddlewares || []);
@@ -1140,6 +1165,53 @@ export class Agent {
   // Public API Methods
   // ============================================================================
 
+  async validateToolExecution({
+    tool,
+    args,
+    options,
+    toolCallId,
+    messages,
+    operationContext,
+  }: {
+    tool: Tool<any, any> | ProviderTool;
+    args: unknown;
+    options?: ToolExecuteOptions;
+    toolCallId?: string;
+    messages?: unknown[];
+    operationContext?: OperationContext;
+  }): Promise<void> {
+    const validators = options?.executionValidators?.tools ?? this.executionValidators?.tools;
+    if (!validators || validators.length === 0) {
+      return;
+    }
+
+    const resolvedToolCallId = toolCallId ?? options?.toolContext?.callId ?? randomUUID();
+    const resolvedOperationContext =
+      operationContext ??
+      (options?.operationId && options.context && options.systemContext
+        ? (options as OperationContext)
+        : undefined);
+    const context: ToolExecutionValidationContext = {
+      type: "tool",
+      agent: this,
+      tool,
+      toolName: tool.name,
+      args,
+      options,
+      operationContext: resolvedOperationContext,
+      toolCallId: resolvedToolCallId,
+      messages: messages ?? options?.toolContext?.messages ?? [],
+      timestamp: new Date(),
+    };
+
+    await runExecutionValidators(
+      validators,
+      context,
+      `Tool ${tool.name} execution blocked by validation.`,
+      "TOOL_VALIDATION_FAILED",
+    );
+  }
+
   /**
    * Generate text response
    */
@@ -4071,6 +4143,11 @@ export class Agent {
       operationId,
       context,
       requestHeaders: options?.requestHeaders ?? options?.parentOperationContext?.requestHeaders,
+      executionValidators: mergeAgentExecutionValidators(
+        options?.parentOperationContext?.executionValidators,
+        this.executionValidators,
+        options?.executionValidators,
+      ),
       systemContext,
       isActive: true,
       logger,
@@ -6351,7 +6428,7 @@ export class Agent {
           options: executionOptions,
         });
 
-        if (isToolDeniedError(errorValue)) {
+        if (isToolDeniedError(errorValue) || isExecutionValidationError(errorValue)) {
           oc.abortController.abort(errorValue);
         }
 
@@ -6367,6 +6444,14 @@ export class Agent {
         return async function* (this: Agent): AsyncGenerator<any, void, void> {
           try {
             await oc.traceContext.withSpan(toolSpan, async () => {
+              await this.validateToolExecution({
+                tool: tool as Tool<any, any>,
+                args,
+                options: executionOptions,
+                toolCallId,
+                messages,
+                operationContext: oc,
+              });
               await runToolStartHooks();
             });
 
@@ -6426,6 +6511,14 @@ export class Agent {
 
       return oc.traceContext.withSpan(toolSpan, async () => {
         try {
+          await this.validateToolExecution({
+            tool: tool as Tool<any, any>,
+            args,
+            options: executionOptions,
+            toolCallId,
+            messages,
+            operationContext: oc,
+          });
           // Call tool start hook - can throw ToolDeniedError
           await runToolStartHooks();
 
@@ -6946,6 +7039,15 @@ export class Agent {
       executionOptions.toolContext?.callId ?? randomUUID(),
     );
 
+    await this.validateToolExecution({
+      tool,
+      args,
+      options: executionOptions,
+      toolCallId: executionOptions.toolContext?.callId,
+      messages: executionOptions.toolContext?.messages ?? [],
+      operationContext: oc,
+    });
+
     const tools: Record<string, any> = {
       [tool.name]: tool,
     };

packages/core/src/agent/errors/client-http-errors.ts

@@ -46,6 +46,12 @@ export type ToolDeniedErrorCode =
   | "TOOL_PLAN_REQUIRED"
   | "TOOL_QUOTA_EXCEEDED";
 
+export type ExecutionValidationErrorCode =
+  | "EXECUTION_VALIDATION_FAILED"
+  | "TOOL_VALIDATION_FAILED"
+  | "WORKFLOW_VALIDATION_FAILED"
+  | string;
+
 /**
  * Error thrown when a tool execution is denied by a controller or policy layer
  */
@@ -72,3 +78,31 @@ export function isClientHTTPError(error: unknown): error is ClientHTTPError {
 export function isToolDeniedError(error: unknown): error is ToolDeniedError {
   return error instanceof ToolDeniedError;
 }
+
+/**
+ * Error thrown when an execution validator denies a tool or workflow execution.
+ */
+export class ExecutionValidationError extends ClientHTTPError {
+  readonly metadata?: Record<string, unknown>;
+
+  constructor({
+    targetName = "ExecutionValidationError",
+    message,
+    code = "EXECUTION_VALIDATION_FAILED",
+    httpStatus = 403,
+    metadata,
+  }: {
+    targetName?: string;
+    message: string;
+    code?: ExecutionValidationErrorCode;
+    httpStatus?: ClientHttpErrorCode;
+    metadata?: Record<string, unknown>;
+  }) {
+    super(targetName, httpStatus, code, message);
+    this.metadata = metadata;
+  }
+}
+
+export function isExecutionValidationError(error: unknown): error is ExecutionValidationError {
+  return error instanceof ExecutionValidationError;
+}

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

@@ -5,10 +5,17 @@ export type { VoltAgentError } from "./voltagent-error";
 export type { AbortError } from "./abort-error";
 export type { BailError } from "./bail-error";
 export type { MiddlewareAbortError, MiddlewareAbortOptions } from "./middleware-abort-error";
+export type {
+  ClientHttpErrorCode,
+  ExecutionValidationErrorCode,
+  ToolDeniedErrorCode,
+} from "./client-http-errors";
 export {
   ToolDeniedError,
   ClientHTTPError,
+  ExecutionValidationError,
   isClientHTTPError,
+  isExecutionValidationError,
   isToolDeniedError,
 } from "./client-http-errors";
 export { createAbortError, isAbortError } from "./abort-error";

packages/core/src/agent/types.ts

@@ -32,6 +32,7 @@ import type { VoltAgentTextStreamPart } from "./subagent/types";
 
 import type { Logger } from "@voltagent/internal";
 import type { LocalScorerDefinition, SamplingPolicy } from "../eval/runtime";
+import type { AgentExecutionValidators } from "../execution-validation";
 import type { MemoryOptions, MemoryStorageMetadata, WorkingMemorySummary } from "../memory/types";
 import type { VoltAgentObservability } from "../observability";
 import type { ModelRouterModelId } from "../registries/model-provider-types.generated";
@@ -695,6 +696,9 @@ export type AgentOptions = {
   // Hooks
   hooks?: AgentHooks;
 
+  // Execution validators
+  executionValidators?: AgentExecutionValidators;
+
   // Guardrails
   inputGuardrails?: InputGuardrail[];
   outputGuardrails?: OutputGuardrail<any>[];
@@ -1083,6 +1087,9 @@ export interface CommonGenerateOptions {
 
   // Optional hooks to be included only during the operation call and not persisted in the agent
   hooks?: AgentHooks;
+
+  // Optional execution validators to include only during this operation
+  executionValidators?: AgentExecutionValidators;
 }
 
 /**
@@ -1312,6 +1319,9 @@ export type OperationContext = {
   /** HTTP request headers associated with this operation, when available */
   readonly requestHeaders?: Record<string, string>;
 
+  /** Execution validators active for this operation */
+  readonly executionValidators?: AgentExecutionValidators;
+
   /** System-managed context map for internal operation tracking */
   readonly systemContext: Map<string | symbol, unknown>;