feat(core): support conditional, function-based tool approvals (#17337)

Co-authored-by: Mastra Code (anthropic/claude-opus-4-8) <noreply@mastra.ai>

Author: abhiaiyer91

.changeset/conditional-tool-approvals.md

@@ -0,0 +1,19 @@
+---
+'@mastra/core': minor
+'@mastra/mcp': patch
+---
+
+Support conditional, function-based tool approvals.
+
+- MCP tools that wrap a server-level `requireToolApproval` function are now honored end-to-end. The per-tool approval function was previously dropped when the agent converted MCP tools (it kept only the boolean flag), so conditional approval silently fell back to always-on. `CoreToolBuilder` now preserves a `needsApprovalFn` attached directly to a tool instance.
+- The global `requireToolApproval` option on `agent.stream`/`agent.generate` now accepts a function in addition to a boolean. It is evaluated per tool call with the tool name, arguments, and request context, enabling policies such as regex allowlists on tool names. Returning `true` requires approval for that call; `false` allows it. On error the call defaults to requiring approval. When a function policy is set, tool calls run sequentially so approval suspensions don't race. Durable agents and stored agents continue to accept only a boolean (a function degrades to requiring approval for every call, since their options must be serializable).
+```ts
+// Approve only tool calls whose name is not on an allowlist.
+const allowlist = /^(get|list|search)_/;
+await agent.generate('...', {
+  requireToolApproval: ({ toolName }) => !allowlist.test(toolName),
+});
+```
+
+- Precedence is unchanged from before: a per-tool approval function (`createTool({ requireApproval: fn })` or an MCP-derived `needsApprovalFn`) is authoritative for that tool and overrides the global setting, so a tool can still opt out of approval by returning `false` even when the global option is on. The only new behavior is that the global option may now be a function in addition to a boolean.
+- The previously implicit, runtime-attached per-tool approval predicate is now a typed contract: `@mastra/core` exports `NeedsApprovalFn` and declares the optional `needsApprovalFn` property on the `Tool` class. The MCP client and the agent runtime now share this typed contract instead of reaching through `any`. This is additive — no public API changes.

docs/src/content/en/docs/agents/agent-approval.mdx

@@ -99,6 +99,24 @@ for await (const chunk of stream.fullStream) {
 }
 ```
 
+#### Conditional approval with a function
+
+Instead of a boolean, `requireToolApproval` accepts a function that decides per tool call. It receives the `toolName`, the `args` the model passed, the `requestContext`, and the `workspace`. Return `true` to require approval for that call, or `false` to allow it. This lets you gate approval dynamically — for example, only for tools whose name matches a pattern:
+
+```typescript
+const stream = await agent.stream('Clean up old records', {
+  requireToolApproval: ({ toolName }) => /^delete_/.test(toolName),
+})
+```
+
+A tool's own `requireApproval` setting still takes precedence: if a tool defines its own approval rule, that rule decides for that tool and the function above does not override it. If the function throws, the call requires approval (fail-safe).
+
+:::note
+
+Function-based `requireToolApproval` is only available on regular `stream()` / `generate()` calls. Durable agents and stored agents persist their options, and a function can't be serialized, so they accept only a boolean. If you pass a function in those contexts it falls back to requiring approval for every tool call.
+
+:::
+
 ### Runtime suspension with `suspend()`
 
 A tool can also pause _during_ its `execute` function by calling `suspend()`. This is useful when the tool starts running and then discovers it needs additional user input or confirmation before it can finish.

packages/core/src/agent/__tests__/tool-approval.test.ts

@@ -159,6 +159,190 @@ export function toolApprovalAndSuspensionTests(version: 'v1' | 'v2') {
           expect(toolName).toBe('findUserTool');
         }
       }, 500000);
+
+      it('should evaluate a function-valued global requireToolApproval per tool call', async () => {
+        const execute = vi.fn().mockResolvedValue({ name: 'Dero Israel', email: 'dero@mail.com' });
+        const findUserTool = createTool({
+          id: 'find-user-tool',
+          description: 'Returns the name and email for a user',
+          inputSchema: z.object({ name: z.string() }),
+          execute: async () => execute(),
+        });
+
+        const makeModel = () =>
+          new MockLanguageModelV2({
+            doStream: async () => ({
+              rawCall: { rawPrompt: null, rawSettings: {} },
+              warnings: [],
+              stream: convertArrayToReadableStream([
+                { type: 'stream-start', warnings: [] },
+                { type: 'response-metadata', id: 'id-0', modelId: 'mock-model-id', timestamp: new Date(0) },
+                {
+                  type: 'tool-call',
+                  toolCallId: 'call-1',
+                  toolName: 'findUserTool',
+                  input: '{"name":"Dero Israel"}',
+                  providerExecuted: false,
+                },
+                {
+                  type: 'finish',
+                  finishReason: 'tool-calls',
+                  usage: { inputTokens: 10, outputTokens: 20, totalTokens: 30 },
+                },
+              ]),
+            }),
+          });
+
+        const makeAgent = () =>
+          new Agent({
+            id: 'global-approval-agent',
+            name: 'Global Approval Agent',
+            instructions: 'You can look up users.',
+            model: makeModel(),
+            tools: { findUserTool },
+            memory: new MockMemory(),
+          });
+
+        // Case 1: the policy returns true → the tool call suspends for approval and does not execute.
+        const approveAll = vi.fn().mockReturnValue(true);
+        const suspendingAgent = makeAgent();
+        const suspendStream = await suspendingAgent.stream('Find the user with name - Dero Israel', {
+          memory: { thread: randomUUID(), resource: randomUUID() },
+          requireToolApproval: approveAll,
+        });
+        let approvedToolName = '';
+        for await (const chunk of suspendStream.fullStream) {
+          if (chunk.type === 'tool-call-approval') {
+            approvedToolName = chunk.payload.toolName;
+          }
+        }
+        expect(approveAll).toHaveBeenCalledWith(
+          expect.objectContaining({ toolName: 'findUserTool', args: { name: 'Dero Israel' } }),
+        );
+        expect(approvedToolName).toBe('findUserTool');
+        expect(execute).not.toHaveBeenCalled();
+
+        // Case 2: the policy returns false → the tool runs without requiring approval.
+        const denyApproval = vi.fn().mockReturnValue(false);
+        const runningAgent = makeAgent();
+        const runStream = await runningAgent.stream('Find the user with name - Dero Israel', {
+          memory: { thread: randomUUID(), resource: randomUUID() },
+          requireToolApproval: denyApproval,
+        });
+        let sawApproval = false;
+        for await (const chunk of runStream.fullStream) {
+          if (chunk.type === 'tool-call-approval') {
+            sawApproval = true;
+          }
+        }
+        expect(denyApproval).toHaveBeenCalled();
+        expect(sawApproval).toBe(false);
+        expect(execute).toHaveBeenCalled();
+      }, 500000);
+
+      it('honors a function-valued global requireToolApproval across suspend and resume', async () => {
+        // The function policy lives only in the live JS call (RequestContext.toJSON strips it from
+        // the persisted suspend snapshot). This proves the resume call re-supplies and re-evaluates
+        // the function, so approval survives a real suspend -> resume cycle without serialization.
+        let callCount = 0;
+        const mockModel = new MockLanguageModelV2({
+          doStream: async () => {
+            callCount++;
+            if (callCount === 1) {
+              return {
+                rawCall: { rawPrompt: null, rawSettings: {} },
+                warnings: [],
+                stream: convertArrayToReadableStream([
+                  { type: 'stream-start', warnings: [] },
+                  { type: 'response-metadata', id: 'id-0', modelId: 'mock-model-id', timestamp: new Date(0) },
+                  {
+                    type: 'tool-call',
+                    toolCallId: 'call-1',
+                    toolName: 'findUserTool',
+                    input: '{"name":"Dero Israel"}',
+                    providerExecuted: false,
+                  },
+                  {
+                    type: 'finish',
+                    finishReason: 'tool-calls',
+                    usage: { inputTokens: 10, outputTokens: 20, totalTokens: 30 },
+                  },
+                ]),
+              };
+            }
+            return {
+              rawCall: { rawPrompt: null, rawSettings: {} },
+              warnings: [],
+              stream: convertArrayToReadableStream([
+                { type: 'stream-start', warnings: [] },
+                { type: 'response-metadata', id: 'id-0', modelId: 'mock-model-id', timestamp: new Date(0) },
+                {
+                  type: 'tool-call',
+                  toolCallId: 'call-2',
+                  toolName: 'findUserTool',
+                  input: '{"name":"Dero Israel", "resumeData": { "approved": true }}',
+                  providerExecuted: false,
+                },
+                {
+                  type: 'finish',
+                  finishReason: 'tool-calls',
+                  usage: { inputTokens: 10, outputTokens: 20, totalTokens: 30 },
+                },
+              ]),
+            };
+          },
+        });
+
+        const findUserTool = createTool({
+          id: 'find-user-tool',
+          description: 'Returns the name and email for a user',
+          inputSchema: z.object({ name: z.string() }),
+          execute: async input => mockFindUser(input) as Promise<Record<string, any>>,
+        });
+
+        const resumeAgent = new Agent({
+          id: 'resume-approval-agent',
+          name: 'Resume Approval Agent',
+          instructions: 'You can look up users.',
+          model: mockModel,
+          tools: { findUserTool },
+          memory: new MockMemory(),
+        });
+
+        const mastra = new Mastra({ agents: { resumeAgent }, logger: false, storage: mockStorage });
+        const agent = mastra.getAgent('resumeAgent');
+        const memory = { thread: randomUUID(), resource: randomUUID() };
+        const requireToolApproval = vi.fn().mockReturnValue(true);
+
+        mockFindUser.mockClear();
+
+        // First call: the function policy requires approval, so the tool suspends.
+        const suspendStream = await agent.stream('Find the user with name - Dero Israel', {
+          memory,
+          requireToolApproval,
+        });
+        let toolName = '';
+        for await (const chunk of suspendStream.fullStream) {
+          if (chunk.type === 'tool-call-approval') {
+            toolName = chunk.payload.toolName;
+          }
+        }
+        expect(toolName).toBe('findUserTool');
+        expect(mockFindUser).not.toHaveBeenCalled();
+
+        // Resume call: re-supplies the same function policy. Approval is granted, tool executes.
+        const resumeStream = await agent.stream('Approve', { memory, requireToolApproval });
+        for await (const _chunk of resumeStream.fullStream) {
+          // drain
+        }
+        const toolResults = await resumeStream.toolResults;
+        const toolCall = toolResults?.find((result: any) => result.payload.toolName === 'findUserTool')?.payload;
+
+        // The policy was evaluated on both the suspend and resume passes (function survived resume).
+        expect(requireToolApproval.mock.calls.length).toBeGreaterThanOrEqual(2);
+        expect(mockFindUser).toHaveBeenCalled();
+        expect((toolCall?.result as any)?.name).toBe('Dero Israel');
+      }, 500000);
     });
   });
 }

packages/core/src/agent/__tests__/tools.test.ts

@@ -1387,6 +1387,54 @@ describe('requireApproval property preservation', () => {
       }
     }
   });
+
+  it('should preserve a needsApprovalFn attached directly to a tool (MCP shape) through convertTools', async () => {
+    const mockModel = new MockLanguageModelV2({
+      doGenerate: async () => ({
+        rawCall: { rawPrompt: null, rawSettings: {} },
+        finishReason: 'stop',
+        usage: { inputTokens: 1, outputTokens: 1, totalTokens: 2 },
+        text: 'ok',
+        content: [{ type: 'text', text: 'ok' }],
+        warnings: [],
+      }),
+    });
+
+    // Mirror how the MCP client builds tools: boolean requireApproval plus a
+    // server-level approval function attached directly as needsApprovalFn.
+    const needsApprovalFn = (args: any) => args.amount > 100;
+    const mcpStyleTool = createTool({
+      id: 'transfer-funds',
+      description: 'Transfer funds',
+      inputSchema: z.object({ amount: z.number() }),
+      requireApproval: true,
+      execute: async ({ amount }) => ({ success: true, amount }),
+    });
+    mcpStyleTool.needsApprovalFn = needsApprovalFn;
+
+    const agent = new Agent({
+      id: 'test-agent',
+      name: 'Test Agent',
+      instructions: 'Test agent for conditional approval',
+      model: mockModel,
+    });
+
+    const tools = await agent['convertTools']({
+      requestContext: new RequestContext(),
+      methodType: 'generate',
+      toolsets: {
+        banking: {
+          transferFunds: mcpStyleTool,
+        },
+      },
+    });
+
+    expect(tools.transferFunds).toBeDefined();
+    expect((tools.transferFunds as any).requireApproval).toBe(true);
+    // The conditional approval function must survive conversion so tool-call-step
+    // can evaluate it per call instead of falling back to the boolean flag.
+    expect((tools.transferFunds as any).needsApprovalFn).toBe(needsApprovalFn);
+  });
 });
 
 describe('sub-agent prompt input normalization (GitHub #14154)', () => {

packages/core/src/agent/agent.types.ts

@@ -9,7 +9,7 @@ import type { VersionOverrides } from '../mastra/types';
 import type { ObservabilityContext, TracingOptions } from '../observability';
 import type { ErrorProcessorOrWorkflow, InputProcessorOrWorkflow, OutputProcessorOrWorkflow } from '../processors';
 import type { RequestContext } from '../request-context';
-import type { ToolPayloadTransformPolicy } from '../tools';
+import type { RequireToolApproval, ToolPayloadTransformPolicy } from '../tools';
 import type { OutputWriter, WorkflowRunState } from '../workflows/types';
 import type { MessageListInput } from './message-list';
 import type {
@@ -568,8 +568,12 @@ export type AgentExecutionOptionsBase<OUTPUT> = {
    */
   isTaskComplete?: StreamIsTaskCompleteConfig;
 
-  /** Require approval for all tool calls */
-  requireToolApproval?: boolean;
+  /**
+   * Require approval for tool calls. Pass `true` to require approval for every tool call,
+   * or a function evaluated per call (with the tool name, args, and request context) to
+   * decide conditionally — e.g. to gate approval by a regex on the tool name.
+   */
+  requireToolApproval?: RequireToolApproval;
 
   /** Automatically resume suspended tools */
   autoResumeSuspendedTools?: boolean;

packages/core/src/agent/durable/preparation.ts

@@ -327,7 +327,10 @@ export async function prepareForDurableExecution<OUTPUT = undefined>(
       toolChoice: execOptions?.toolChoice as any,
       activeTools: execOptions?.activeTools,
       temperature: execOptions?.modelSettings?.temperature,
-      requireToolApproval: execOptions?.requireToolApproval,
+      // Durable runs serialize their options, so a function-valued global approval policy
+      // can't be persisted. Degrade safely by requiring approval for every tool call.
+      requireToolApproval:
+        typeof execOptions?.requireToolApproval === 'function' ? true : execOptions?.requireToolApproval,
       toolCallConcurrency: execOptions?.toolCallConcurrency,
       autoResumeSuspendedTools: execOptions?.autoResumeSuspendedTools,
       maxProcessorRetries: execOptions?.maxProcessorRetries,

packages/core/src/agent/durable/utils/resolve-runtime.ts

@@ -5,6 +5,7 @@ import type { StreamInternal } from '../../../loop/types';
 import type { Mastra } from '../../../mastra';
 import type { MastraMemory } from '../../../memory/memory';
 import { RequestContext } from '../../../request-context';
+import { getNeedsApprovalFn } from '../../../tools/toolchecks';
 import type { CoreTool } from '../../../tools/types';
 import type { Workspace } from '../../../workspace';
 import { MessageList } from '../../message-list';
@@ -246,8 +247,9 @@ export function resolveTool(toolName: string, mastra?: Mastra): CoreTool | undef
  * Check if a tool requires human approval.
  *
  * If the tool has a `needsApprovalFn`, it takes precedence over both the
- * global `requireToolApproval` flag and the tool-level `requireApproval` flag.
- * This matches the behavior of the non-durable agent's tool-call-step.
+ * global `requireToolApproval` flag and the tool-level `requireApproval` flag
+ * (e.g. skill tools return `false` to suppress approval). On error the call
+ * defaults to requiring approval (safe default).
  */
 export async function toolRequiresApproval(
   tool: CoreTool,
@@ -257,9 +259,10 @@ export async function toolRequiresApproval(
   let requires = !!(globalRequireApproval || (tool as any).requireApproval);
 
   // needsApprovalFn overrides all other flags (e.g., skill tools return false)
-  if ((tool as any).needsApprovalFn) {
+  const needsApprovalFn = getNeedsApprovalFn(tool);
+  if (needsApprovalFn) {
     try {
-      requires = await (tool as any).needsApprovalFn(args ?? {});
+      requires = !!(await needsApprovalFn(args ?? {}));
     } catch {
       // On error, default to requiring approval (safe default)
       requires = true;

packages/core/src/agent/workflows/prepare-stream/index.ts

@@ -8,7 +8,7 @@ import type { Span, SpanType } from '../../../observability';
 import { InternalSpans } from '../../../observability';
 import type { RequestContext } from '../../../request-context';
 import { MastraModelOutput } from '../../../stream';
-import type { ToolPayloadTransformPolicy } from '../../../tools';
+import type { RequireToolApproval, ToolPayloadTransformPolicy } from '../../../tools';
 import { createWorkflow } from '../../../workflows/workflow';
 import type { Workspace } from '../../../workspace/workspace';
 import type { InnerAgentExecutionOptions } from '../../agent.types';
@@ -35,7 +35,7 @@ interface CreatePrepareStreamWorkflowOptions<OUTPUT = undefined> {
   memory?: MastraMemory;
   returnScorerData?: boolean;
   saveQueueManager?: SaveQueueManager;
-  requireToolApproval?: boolean;
+  requireToolApproval?: RequireToolApproval;
   toolCallConcurrency?: number;
   resumeContext?: {
     resumeData: any;

packages/core/src/agent/workflows/prepare-stream/stream-step.ts

@@ -8,7 +8,7 @@ import type { MemoryConfigInternal } from '../../../memory/types';
 import { resolveObservabilityContext } from '../../../observability';
 import { RequestContext } from '../../../request-context';
 import { MastraModelOutput } from '../../../stream';
-import type { ToolPayloadTransformPolicy } from '../../../tools';
+import type { RequireToolApproval, ToolPayloadTransformPolicy } from '../../../tools';
 import { createStep } from '../../../workflows/workflow';
 import type { Workspace } from '../../../workspace/workspace';
 import type { SaveQueueManager } from '../../save-queue';
@@ -20,7 +20,7 @@ interface StreamStepOptions {
   capabilities: AgentCapabilities;
   runId: string;
   returnScorerData?: boolean;
-  requireToolApproval?: boolean;
+  requireToolApproval?: RequireToolApproval;
   toolCallConcurrency?: number;
   resumeContext?: {
     resumeData: any;