Python: Honor Foundry Toolbox approval metadata - #10136

Motivation & Context

Foundry Toolbox discovery exposes approval configuration in each tool's _meta.tool_configuration.require_approval, but Python ignored that configuration. A live hosted Responses reproduction confirmed that a tool configured with require_approval: "always" executed without an mcp_approval_request. An explicit local approval policy paused the same tool correctly.

This fixes metadata-based approval selection before local tool execution, without interpreting Foundry-specific metadata for ordinary MCP servers.

Description & Review Guide

• What are the major changes? Add synchronous callable policies to MCP approval_mode and compose the Foundry metadata parser through that option rather than an inheritance hook. Callables receive the discovered mcp.types.Tool or mcp.types.Prompt and must return "always_require" or "never_require" for every item, including their default decision. Invalid results, including None, fail discovery explicitly. FoundryToolbox.approval_mode is now an explicit, typed constructor parameter.
• What is the impact of these changes? For Toolbox, omitted/None selects metadata-based approval. Explicit scalar, dictionary, or callable policies replace metadata handling entirely. Ordinary MCP None and static-policy behavior remain unchanged. Toolbox metadata supports "always", "never", and always/never filters using remote/original tool names and read_only. Filter criteria are combined, always wins overlaps, and unmatched filter-policy tools require approval. Missing metadata preserves the no-approval default; malformed metadata fails discovery instead of silently disabling approval. Callable policies refresh retained functions, with updates staged until the complete discovery snapshot validates. Failed refreshes preserve the previous snapshot and approval modes. Static policies preserve caller customizations on retained functions.
• What do you want reviewers to focus on? Approval-policy precedence, exact remote-name matching, conservative filter resolution, and failure atomicity across paginated discovery and reconnects. Offline regressions exercise streaming/non-streaming approval and rejection, resume/replay, exactly-once execution, and the hosted Responses approval envelope.

Before, applications needed a blanket local override to guarantee an approval pause:

from agent_framework_foundry_hosting import FoundryToolbox
from azure.identity.aio import DefaultAzureCredential

credential = DefaultAzureCredential()
toolbox = FoundryToolbox(
    credential,
    url="https://toolbox.example/mcp",
    approval_mode="always_require",
)

After, the default honors each discovered tool's Foundry configuration:

from agent_framework_foundry_hosting import FoundryToolbox
from azure.identity.aio import DefaultAzureCredential

credential = DefaultAzureCredential()
toolbox = FoundryToolbox(
    credential,
    url="https://toolbox.example/mcp",
)

Use approval_mode="never_require" to disable local Toolbox approval explicitly. Connection and credential ownership, approval persistence, and the function-loop protocol are unchanged. Streaming and non-streaming execution use the same policy; both pause before tool execution when approval is required. The implementation and callable-based composition were reviewed and approved by the maintainer during the live-reproduction follow-up. The final patch was validated locally; the patched package has not been redeployed to the live reproduction.

Local validation: uv run --directory python poe test -P core passed (9,400 passed, 20 skipped, 2 xfailed); uv run --directory python poe test -P foundry_hosting passed (1,092 passed, 36 integration tests deselected). uv run --directory python poe syntax -P core, uv run --directory python poe syntax -P foundry_hosting, uv run --directory python poe pyright -P core, uv run --directory python poe pyright -P foundry_hosting, uv run --directory python poe test-typing -P core, and uv run --directory python poe test-typing -P foundry_hosting all passed. Both test-typing runs passed all five configured checkers. git diff --check passed.

Related Issue

No linked issue. This draft follows a reproduced bug and maintainer-reviewed implementation; issue linkage remains outstanding. No competing Python Toolbox approval-parsing PR was found.

AI Assistance

• No material AI assistance was used.
• This is an AI-assisted contribution. I reviewed, understood, and verified all submitted content and accept responsibility for it.

AI assistance details: Copilot assisted with investigation, implementation, regression tests, documentation, and this PR description.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR links to an agreed issue with no competing open PR, or the Related Issue section documents a trivial-change or repository-automation exception.
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.