Python: Enforce approval_mode in Claude and GitHub Copilot agents

[eavanvalkenburg]

Motivation and Context

Tools declared with approval_mode="always_require" are silently executed by ClaudeAgent and GitHubCopilotAgent because their SDK-managed tool-calling loops invoke FunctionTool.invoke() directly inside per-package handlers, bypassing the _try_execute_function_calls approval gate that protects the standard chat-client pipeline.

PR #5494 proposed a fix inside FunctionTool.invoke() itself (an _approved=True parameter), but as discussed on that PR any flag on the tool can be spoofed by any code with the same level of access. The security boundary must be the agent that owns the tool-calling loop, not the tool.

Description

Enforce approval_mode="always_require" at the agent boundary for the two affected packages:

• New per-agent option on_function_approval on ClaudeAgentOptions and GitHubCopilotOptions. The callback receives a FunctionCallContent describing the pending call (name + arguments) and returns bool (sync or async).
• The existing tool-handler closure each agent supplies to its SDK now gates on func_tool.approval_mode == "always_require" before calling FunctionTool.invoke(). Approval flow:
  • No callback → deny by default with an explanatory tool-error.
  • Callback returns truthy → execute normally.
  • Callback returns falsy → deny with explanatory tool-error.
  • Callback raises → deny safely (logged via logger.exception) so user code crashes don't accidentally allow execution.
• Deny path returns a result the model can interpret: Claude returns text content describing the denial; Copilot returns ToolResult(result_type="failure", error="approval_denied"). This lets the LLM react gracefully (apologise, try a different path) instead of silently failing.
• FunctionTool and core APIs are untouched, so the rejected _approved/ToolApprovalRequiredException surface is not introduced.

Coverage

• packages/claude/tests/test_claude_agent.py — 6 tests in TestClaudeAgentFunctionApproval.
• packages/github_copilot/tests/test_github_copilot_agent.py — 6 tests in TestGitHubCopilotAgentFunctionApproval.

Each suite exercises: deny-by-default, sync False, sync True, async True, callback-raises → deny, and no-op for never_require tools (with payload-shape assertions on the FunctionCallContent passed to the callback).

Samples

• samples/02-agents/providers/anthropic/anthropic_claude_with_function_approval.py
• samples/02-agents/providers/github_copilot/github_copilot_with_function_approval.py

Both demonstrate sync callback, async callback, and the deny-by-default fallback.

Audit of other packages

grep for FunctionTool.invoke(...) call sites across packages/: only core/_agents.py (Agent-as-tool, uses the standard pipeline transitively) and hyperlight/_execute_code_tool.py (internal sandbox tool, not a user-supplied always-require target) remain. CopilotStudio doesn't accept FunctionTool. No other production fixes required.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? If yes, add "[BREAKING]" prefix to the title of the PR.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/claude/agent_framework_claude
_agent.py	305	28	90%	385–386, 390, 402, 410–412, 414–415, 445–447, 466, 470, 472, 476, 485, 531, 534, 574, 579–580, 654, 741, 767–770
packages/github_copilot/agent_framework_github_copilot
_agent.py	311	13	95%	45–46, 52, 124, 449, 464–465, 752–753, 791, 794, 861, 886
TOTAL	30638	3559	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
6167	30 💤	0 ❌	0 🔥	1m 39s ⏱️

[Copilot]

Pull request overview

This PR closes a security gap in SDK-managed tool-calling loops by enforcing approval_mode="always_require" at the agent boundary for the Python ClaudeAgent and GitHubCopilotAgent, introducing an explicit approval callback and default-deny behavior when approval is required.

Changes:

• Add on_function_approval callback option to ClaudeAgentOptions and GitHubCopilotOptions, and gate FunctionTool.invoke() behind it for approval_mode="always_require".
• Add unit tests covering deny-by-default, sync/async approval, callback failure, and no-op behavior for non-approval tools.
• Add provider samples demonstrating sync/async approval callbacks and default-deny behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
python/packages/claude/agent_framework_claude/_agent.py	Adds on_function_approval option + approval gating in the Claude SDK MCP tool handler.
python/packages/claude/tests/test_claude_agent.py	Adds tests validating Claude-side approval enforcement behavior.
python/packages/github_copilot/agent_framework_github_copilot/_agent.py	Adds on_function_approval option + approval gating in the Copilot SDK tool handler.
python/packages/github_copilot/tests/test_github_copilot_agent.py	Adds tests validating Copilot-side approval enforcement behavior.
python/samples/02-agents/providers/anthropic/anthropic_claude_with_function_approval.py	New Claude sample showing function-approval callback usage.
python/samples/02-agents/providers/github_copilot/github_copilot_with_function_approval.py	New Copilot sample showing function-approval callback usage.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 86% | Result: All clear

Reviewed: Correctness, Security Reliability, Test Coverage, Design Approach

---

Automated review by eavanvalkenburg's agents