feat: make requireApproval support async functions with turn context

Update the call-level requireApproval function signature to:
- Accept TurnContext as a second parameter
- Support async functions (returning Promise<boolean>)

This enables approval decisions based on conversation state:
- Number of turns completed
- Dynamic approval logic based on context

Updated files:
- src/lib/async-params.ts - Update type definition
- src/lib/model-result.ts - Update type and field
- src/lib/conversation-state.ts - Make toolRequiresApproval and
  partitionToolCalls async, add context parameter
- tests/unit/conversation-state.test.ts - Update tests, add async test
- tests/e2e/call-model-state.test.ts - Update test signature

Author: mattapperson

src/lib/async-params.ts

@@ -45,8 +45,14 @@ export type CallModelInput<TTools extends readonly Tool[] = readonly Tool[]> = {
   stopWhen?: StopWhen<TTools>;
   /** State accessor for multi-turn persistence and approval gates */
   state?: StateAccessor<TTools>;
-  /** Call-level approval check - overrides tool-level requireApproval setting */
-  requireApproval?: (toolCall: ParsedToolCall<TTools[number]>) => boolean;
+  /**
+   * Call-level approval check - overrides tool-level requireApproval setting
+   * Receives the tool call and turn context, can be sync or async
+   */
+  requireApproval?: (
+    toolCall: ParsedToolCall<TTools[number]>,
+    context: TurnContext
+  ) => boolean | Promise<boolean>;
   /** Tool call IDs to approve (for resuming from awaiting_approval status) */
   approveToolCalls?: string[];
   /** Tool call IDs to reject (for resuming from awaiting_approval status) */

src/lib/conversation-state.ts

@@ -3,6 +3,7 @@ import type {
   ConversationState,
   ParsedToolCall,
   Tool,
+  TurnContext,
   UnsentToolResult,
 } from './tool-types.js';
 import { normalizeInputToArray } from './turn-context.js';
@@ -96,16 +97,18 @@ export function appendToMessages(
  * Check if a tool call requires approval
  * @param toolCall - The tool call to check
  * @param tools - Available tools
- * @param callLevelCheck - Optional call-level approval function (overrides tool-level)
+ * @param context - Turn context for the approval check
+ * @param callLevelCheck - Optional call-level approval function (overrides tool-level), can be async
  */
-export function toolRequiresApproval<TTools extends readonly Tool[]>(
+export async function toolRequiresApproval<TTools extends readonly Tool[]>(
   toolCall: ParsedToolCall<TTools[number]>,
   tools: TTools,
-  callLevelCheck?: (toolCall: ParsedToolCall<TTools[number]>) => boolean
-): boolean {
+  context: TurnContext,
+  callLevelCheck?: (toolCall: ParsedToolCall<TTools[number]>, context: TurnContext) => boolean | Promise<boolean>
+): Promise<boolean> {
   // Call-level check takes precedence
   if (callLevelCheck) {
-    return callLevelCheck(toolCall);
+    return callLevelCheck(toolCall, context);
   }
 
   // Fall back to tool-level setting
@@ -115,20 +118,25 @@ export function toolRequiresApproval<TTools extends readonly Tool[]>(
 
 /**
  * Partition tool calls into those requiring approval and those that can auto-execute
+ * @param toolCalls - Tool calls to partition
+ * @param tools - Available tools
+ * @param context - Turn context for the approval check
+ * @param callLevelCheck - Optional call-level approval function (overrides tool-level), can be async
  */
-export function partitionToolCalls<TTools extends readonly Tool[]>(
+export async function partitionToolCalls<TTools extends readonly Tool[]>(
   toolCalls: ParsedToolCall<TTools[number]>[],
   tools: TTools,
-  callLevelCheck?: (toolCall: ParsedToolCall<TTools[number]>) => boolean
-): {
+  context: TurnContext,
+  callLevelCheck?: (toolCall: ParsedToolCall<TTools[number]>, context: TurnContext) => boolean | Promise<boolean>
+): Promise<{
   requiresApproval: ParsedToolCall<TTools[number]>[];
   autoExecute: ParsedToolCall<TTools[number]>[];
-} {
+}> {
   const requiresApproval: ParsedToolCall<TTools[number]>[] = [];
   const autoExecute: ParsedToolCall<TTools[number]>[] = [];
 
   for (const tc of toolCalls) {
-    if (toolRequiresApproval(tc, tools, callLevelCheck)) {
+    if (await toolRequiresApproval(tc, tools, context, callLevelCheck)) {
       requiresApproval.push(tc);
     } else {
       autoExecute.push(tc);

src/lib/model-result.ts

@@ -96,7 +96,14 @@ export interface GetResponseOptions<TTools extends readonly Tool[]> {
   stopWhen?: StopWhen<TTools>;
   // State management for multi-turn conversations
   state?: StateAccessor<TTools>;
-  requireApproval?: (toolCall: ParsedToolCall<TTools[number]>) => boolean;
+  /**
+   * Call-level approval check - overrides tool-level requireApproval setting
+   * Receives the tool call and turn context, can be sync or async
+   */
+  requireApproval?: (
+    toolCall: ParsedToolCall<TTools[number]>,
+    context: TurnContext
+  ) => boolean | Promise<boolean>;
   approveToolCalls?: string[];
   rejectToolCalls?: string[];
 }
@@ -140,7 +147,7 @@ export class ModelResult<TTools extends readonly Tool[]> {
   // State management for multi-turn conversations
   private stateAccessor: StateAccessor<TTools> | null = null;
   private currentState: ConversationState<TTools> | null = null;
-  private requireApprovalFn: ((toolCall: ParsedToolCall<TTools[number]>) => boolean) | null = null;
+  private requireApprovalFn: ((toolCall: ParsedToolCall<TTools[number]>, context: TurnContext) => boolean | Promise<boolean>) | null = null;
   private approvedToolCalls: string[] = [];
   private rejectedToolCalls: string[] = [];
   private isResumingFromApproval = false;
@@ -337,16 +344,18 @@ export class ModelResult<TTools extends readonly Tool[]> {
   ): Promise<boolean> {
     if (!this.options.tools) return false;
 
-    const { requiresApproval: needsApproval, autoExecute } = partitionToolCalls(
+    const turnContext: TurnContext = { numberOfTurns: currentRound };
+
+    const { requiresApproval: needsApproval, autoExecute } = await partitionToolCalls(
       toolCalls as ParsedToolCall<TTools[number]>[],
       this.options.tools,
+      turnContext,
       this.requireApprovalFn ?? undefined
     );
 
     if (needsApproval.length === 0) return false;
 
     // Execute auto-approve tools
-    const turnContext: TurnContext = { numberOfTurns: currentRound };
     const unsentResults = await this.executeAutoApproveTools(autoExecute, turnContext);
 
     // Save state with pending approvals

tests/e2e/call-model-state.test.ts

@@ -154,7 +154,8 @@ describe('State Management Integration', () => {
       });
 
       // Custom function that requires approval for all tools
-      const customRequireApproval = (toolCall: { name: string }) => {
+      // Accepts toolCall and context (TurnContext) as per the updated signature
+      const customRequireApproval = (toolCall: { name: string }, _context: { numberOfTurns: number }) => {
         checkedTools.push(toolCall.name);
         return true; // Always require approval
       };

tests/unit/conversation-state.test.ts

@@ -110,34 +110,48 @@ describe('Conversation State Utilities', () => {
       execute: async () => ({}),
     });
 
-    it('should return true for tools with requireApproval', () => {
+    const context = { numberOfTurns: 1 };
+
+    it('should return true for tools with requireApproval', async () => {
       const toolCall = { id: '1', name: 'dangerous_action', arguments: {} };
-      expect(toolRequiresApproval(toolCall, [toolWithApproval, toolWithoutApproval])).toBe(true);
+      expect(await toolRequiresApproval(toolCall, [toolWithApproval, toolWithoutApproval], context)).toBe(true);
     });
 
-    it('should return false for tools without requireApproval', () => {
+    it('should return false for tools without requireApproval', async () => {
       const toolCall = { id: '1', name: 'safe_action', arguments: {} };
-      expect(toolRequiresApproval(toolCall, [toolWithApproval, toolWithoutApproval])).toBe(false);
+      expect(await toolRequiresApproval(toolCall, [toolWithApproval, toolWithoutApproval], context)).toBe(false);
     });
 
-    it('should return false for unknown tools', () => {
+    it('should return false for unknown tools', async () => {
       const toolCall = { id: '1', name: 'unknown_tool', arguments: {} };
-      expect(toolRequiresApproval(toolCall, [toolWithApproval, toolWithoutApproval])).toBe(false);
+      expect(await toolRequiresApproval(toolCall, [toolWithApproval, toolWithoutApproval], context)).toBe(false);
     });
 
-    it('should use call-level check when provided', () => {
+    it('should use call-level check when provided', async () => {
       const toolCall = { id: '1', name: 'safe_action', arguments: {} };
       const alwaysRequire = () => true;
 
-      expect(toolRequiresApproval(toolCall, [toolWithoutApproval], alwaysRequire)).toBe(true);
+      expect(await toolRequiresApproval(toolCall, [toolWithoutApproval], context, alwaysRequire)).toBe(true);
     });
 
-    it('should call-level check can override tool-level approval', () => {
+    it('should call-level check can override tool-level approval', async () => {
       const toolCall = { id: '1', name: 'dangerous_action', arguments: {} };
       const neverRequire = () => false;
 
       // Call-level check takes precedence
-      expect(toolRequiresApproval(toolCall, [toolWithApproval], neverRequire)).toBe(false);
+      expect(await toolRequiresApproval(toolCall, [toolWithApproval], context, neverRequire)).toBe(false);
+    });
+
+    it('should support async call-level check', async () => {
+      const toolCall = { id: '1', name: 'safe_action', arguments: {} };
+      const asyncCheck = async (_tc: unknown, ctx: { numberOfTurns: number }) => {
+        // Simulate async operation
+        await Promise.resolve();
+        return ctx.numberOfTurns > 0;
+      };
+
+      expect(await toolRequiresApproval(toolCall, [toolWithoutApproval], context, asyncCheck)).toBe(true);
+      expect(await toolRequiresApproval(toolCall, [toolWithoutApproval], { numberOfTurns: 0 }, asyncCheck)).toBe(false);
     });
   });
 
@@ -155,15 +169,18 @@ describe('Conversation State Utilities', () => {
       execute: async () => ({}),
     });
 
-    it('should partition tool calls correctly', () => {
+    const context = { numberOfTurns: 1 };
+
+    it('should partition tool calls correctly', async () => {
       const toolCalls = [
         { id: '1', name: 'needs_approval', arguments: {} },
         { id: '2', name: 'auto_execute', arguments: {} },
       ];
 
-      const { requiresApproval, autoExecute } = partitionToolCalls(
+      const { requiresApproval, autoExecute } = await partitionToolCalls(
         toolCalls,
-        [approvalTool, autoTool]
+        [approvalTool, autoTool],
+        context
       );
 
       expect(requiresApproval).toHaveLength(1);
@@ -172,38 +189,41 @@ describe('Conversation State Utilities', () => {
       expect(autoExecute[0]?.name).toBe('auto_execute');
     });
 
-    it('should handle all tools requiring approval', () => {
+    it('should handle all tools requiring approval', async () => {
       const toolCalls = [
         { id: '1', name: 'needs_approval', arguments: {} },
       ];
 
-      const { requiresApproval, autoExecute } = partitionToolCalls(
+      const { requiresApproval, autoExecute } = await partitionToolCalls(
         toolCalls,
-        [approvalTool, autoTool]
+        [approvalTool, autoTool],
+        context
       );
 
       expect(requiresApproval).toHaveLength(1);
       expect(autoExecute).toHaveLength(0);
     });
 
-    it('should handle all tools auto-executing', () => {
+    it('should handle all tools auto-executing', async () => {
       const toolCalls = [
         { id: '1', name: 'auto_execute', arguments: {} },
       ];
 
-      const { requiresApproval, autoExecute } = partitionToolCalls(
+      const { requiresApproval, autoExecute } = await partitionToolCalls(
         toolCalls,
-        [approvalTool, autoTool]
+        [approvalTool, autoTool],
+        context
       );
 
       expect(requiresApproval).toHaveLength(0);
       expect(autoExecute).toHaveLength(1);
     });
 
-    it('should handle empty tool calls', () => {
-      const { requiresApproval, autoExecute } = partitionToolCalls(
+    it('should handle empty tool calls', async () => {
+      const { requiresApproval, autoExecute } = await partitionToolCalls(
         [],
-        [approvalTool, autoTool]
+        [approvalTool, autoTool],
+        context
       );
 
       expect(requiresApproval).toHaveLength(0);