feat: support async function-based requireApproval on tool definitions

The tool-level requireApproval now supports both boolean values and async
functions that receive the tool's input params and turn context, matching
the call-level requireApproval signature.

This enables dynamic approval decisions based on:
- Tool arguments (e.g., require approval only for dangerous parameter values)
- Turn context (e.g., require approval after a certain number of turns)

Changes:
- Add ToolApprovalCheck type for function-based approval
- Update BaseToolFunction and all tool config types
- Update toolRequiresApproval to handle function-based approval
- Add unit tests for function-based tool-level approval
- Export ToolApprovalCheck type from index

Author: mattapperson

src/index.ts

@@ -29,6 +29,7 @@ export type {
   StopCondition,
   StopWhen,
   Tool,
+  ToolApprovalCheck,
   ToolExecutionResult,
   ToolExecutionResultUnion,
   ToolPreliminaryResultEvent,

src/lib/conversation-state.ts

@@ -113,7 +113,17 @@ export async function toolRequiresApproval<TTools extends readonly Tool[]>(
 
   // Fall back to tool-level setting
   const tool = tools.find(t => t.function.name === toolCall.name);
-  return tool?.function.requireApproval ?? false;
+  if (!tool) return false;
+
+  const requireApproval = tool.function.requireApproval;
+
+  // If it's a function, call it with the tool's arguments and context
+  if (typeof requireApproval === 'function') {
+    return requireApproval(toolCall.arguments, context);
+  }
+
+  // Otherwise treat as boolean
+  return requireApproval ?? false;
 }
 
 /**

src/lib/tool-types.ts

@@ -58,6 +58,16 @@ export type NextTurnParamsFunctions<TInput> = {
   ) => NextTurnParamsContext[K] | Promise<NextTurnParamsContext[K]>;
 };
 
+/**
+ * Tool-level approval check function type
+ * Receives the tool's input params and turn context
+ * Returns true if approval is required, false otherwise
+ */
+export type ToolApprovalCheck<TInput> = (
+  params: TInput,
+  context: TurnContext
+) => boolean | Promise<boolean>;
+
 /**
  * Base tool function interface with inputSchema
  */
@@ -66,8 +76,11 @@ export interface BaseToolFunction<TInput extends ZodObject<ZodRawShape>> {
   description?: string;
   inputSchema: TInput;
   nextTurnParams?: NextTurnParamsFunctions<z.infer<TInput>>;
-  /** Whether this tool requires human approval before execution */
-  requireApproval?: boolean;
+  /**
+   * Whether this tool requires human approval before execution
+   * Can be a boolean or an async function that receives the tool's input params and context
+   */
+  requireApproval?: boolean | ToolApprovalCheck<z.infer<TInput>>;
 }
 
 /**

src/lib/tool.ts

@@ -6,6 +6,7 @@ import {
   type ToolWithGenerator,
   type ManualTool,
   type NextTurnParamsFunctions,
+  type ToolApprovalCheck,
 } from "./tool-types.js";
 
 /**
@@ -21,8 +22,11 @@ type RegularToolConfigWithOutput<
   outputSchema: TOutput;
   eventSchema?: undefined;
   nextTurnParams?: NextTurnParamsFunctions<z.infer<TInput>>;
-  /** Whether this tool requires human approval before execution */
-  requireApproval?: boolean;
+  /**
+   * Whether this tool requires human approval before execution
+   * Can be a boolean or an async function that receives the tool's input params and context
+   */
+  requireApproval?: boolean | ToolApprovalCheck<z.infer<TInput>>;
   execute: (
     params: z.infer<TInput>,
     context?: TurnContext
@@ -42,8 +46,11 @@ type RegularToolConfigWithoutOutput<
   outputSchema?: undefined;
   eventSchema?: undefined;
   nextTurnParams?: NextTurnParamsFunctions<z.infer<TInput>>;
-  /** Whether this tool requires human approval before execution */
-  requireApproval?: boolean;
+  /**
+   * Whether this tool requires human approval before execution
+   * Can be a boolean or an async function that receives the tool's input params and context
+   */
+  requireApproval?: boolean | ToolApprovalCheck<z.infer<TInput>>;
   execute: (
     params: z.infer<TInput>,
     context?: TurnContext
@@ -64,8 +71,11 @@ type GeneratorToolConfig<
   eventSchema: TEvent;
   outputSchema: TOutput;
   nextTurnParams?: NextTurnParamsFunctions<z.infer<TInput>>;
-  /** Whether this tool requires human approval before execution */
-  requireApproval?: boolean;
+  /**
+   * Whether this tool requires human approval before execution
+   * Can be a boolean or an async function that receives the tool's input params and context
+   */
+  requireApproval?: boolean | ToolApprovalCheck<z.infer<TInput>>;
   execute: (
     params: z.infer<TInput>,
     context?: TurnContext
@@ -80,8 +90,11 @@ type ManualToolConfig<TInput extends ZodObject<ZodRawShape>> = {
   description?: string;
   inputSchema: TInput;
   nextTurnParams?: NextTurnParamsFunctions<z.infer<TInput>>;
-  /** Whether this tool requires human approval before execution */
-  requireApproval?: boolean;
+  /**
+   * Whether this tool requires human approval before execution
+   * Can be a boolean or an async function that receives the tool's input params and context
+   */
+  requireApproval?: boolean | ToolApprovalCheck<z.infer<TInput>>;
   execute: false;
 };
 

tests/unit/conversation-state.test.ts

@@ -153,6 +153,74 @@ describe('Conversation State Utilities', () => {
       expect(await toolRequiresApproval(toolCall, [toolWithoutApproval], context, asyncCheck)).toBe(true);
       expect(await toolRequiresApproval(toolCall, [toolWithoutApproval], { numberOfTurns: 0 }, asyncCheck)).toBe(false);
     });
+
+    it('should support function-based tool-level requireApproval', async () => {
+      // Tool with function-based approval that checks params
+      const toolWithFunctionApproval = tool({
+        name: 'conditional_action',
+        inputSchema: z.object({ dangerous: z.boolean() }),
+        requireApproval: (params) => params.dangerous === true,
+        execute: async () => ({}),
+      });
+
+      // Safe action - should not require approval
+      const safeCall = { id: '1', name: 'conditional_action', arguments: { dangerous: false } };
+      expect(await toolRequiresApproval(safeCall, [toolWithFunctionApproval], context)).toBe(false);
+
+      // Dangerous action - should require approval
+      const dangerousCall = { id: '2', name: 'conditional_action', arguments: { dangerous: true } };
+      expect(await toolRequiresApproval(dangerousCall, [toolWithFunctionApproval], context)).toBe(true);
+    });
+
+    it('should support async function-based tool-level requireApproval', async () => {
+      // Tool with async function-based approval
+      const toolWithAsyncApproval = tool({
+        name: 'async_conditional',
+        inputSchema: z.object({ value: z.number() }),
+        requireApproval: async (params, ctx) => {
+          // Simulate async operation
+          await Promise.resolve();
+          // Require approval if value > 100 OR after first turn
+          return params.value > 100 || ctx.numberOfTurns > 1;
+        },
+        execute: async () => ({}),
+      });
+
+      // Low value, first turn - no approval needed
+      const lowValueCall = { id: '1', name: 'async_conditional', arguments: { value: 50 } };
+      expect(await toolRequiresApproval(lowValueCall, [toolWithAsyncApproval], { numberOfTurns: 1 })).toBe(false);
+
+      // High value - approval needed
+      const highValueCall = { id: '2', name: 'async_conditional', arguments: { value: 150 } };
+      expect(await toolRequiresApproval(highValueCall, [toolWithAsyncApproval], { numberOfTurns: 1 })).toBe(true);
+
+      // Low value but second turn - approval needed
+      expect(await toolRequiresApproval(lowValueCall, [toolWithAsyncApproval], { numberOfTurns: 2 })).toBe(true);
+    });
+
+    it('should pass context to function-based tool-level approval', async () => {
+      const receivedContexts: Array<{ numberOfTurns: number }> = [];
+
+      const toolWithContextCheck = tool({
+        name: 'context_checker',
+        inputSchema: z.object({}),
+        requireApproval: (_params, ctx) => {
+          receivedContexts.push(ctx);
+          return ctx.numberOfTurns > 2;
+        },
+        execute: async () => ({}),
+      });
+
+      const toolCall = { id: '1', name: 'context_checker', arguments: {} };
+
+      await toolRequiresApproval(toolCall, [toolWithContextCheck], { numberOfTurns: 1 });
+      await toolRequiresApproval(toolCall, [toolWithContextCheck], { numberOfTurns: 3 });
+
+      expect(receivedContexts).toEqual([
+        { numberOfTurns: 1 },
+        { numberOfTurns: 3 },
+      ]);
+    });
   });
 
   describe('partitionToolCalls', () => {