feat(ai): add toolNeedsApproval option

[lgrammel]

Background

You may want to enable or disable tool approvals for specific tools, irrespective of the tool approval setting on the tool itself. This is particularly relevant for 3rd party tools where you cannot control the needsApproval setting without wrapping the tool.

Summary

Introduce toolNeedsApproval option on generateText, streamText, and ToolLoopAgent. The toolNeedsApproval option takes precedence over the needsApproval property that might be defined on a specific tool.

Example

const result = await generateText({
  // ...
  tools: { weather },
  toolNeedsApproval: {
    weather: true, // or an approval function
  },
});

const agent = new ToolLoopAgent({
  // ...
  tools: { weather: weatherTool },
  toolNeedsApproval: { weather: true },
});

Limitations

Provider-executed tools will get executed provider-side without considering the tool approval setting.

Manual Verification

• run / test examples/ai-functions/src/generate-text/openai/tool-approval-user-defined.ts
• run / test examples/ai-functions/src/stream-text/openai/tool-approval-user-defined.ts
• run / test examples/ai-functions/src/agent/openai/generate-tool-approval.ts

Future Work

• introduce isProviderExecuted flag on tools and exclude from approval list
• support a single catch all function for toolNeedApproval