Python: allow middleware to repair function arguments

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Function-call arguments are currently schema-validated before function middleware runs. When a provider or model returns a repairable shape that differs from the declared schema, middleware never receives the invocation and cannot normalize it at the supported tool boundary.

This change makes function middleware the pre-validation seam while preserving final type validation, approval binding, error behavior, and security enforcement.

Description & Review Guide

• What are the major changes?
  • Pass raw JSON-parsed function arguments into FunctionInvocationContext, then perform final validation immediately before tool execution.
  • Preserve the existing argument-validation error contract and direct FunctionTool.invoke() behavior.
  • Require a replacement approval when middleware changes arguments covered by an earlier approval.
  • Fail closed when arguments change after security middleware has inspected them, and redact security-resolved values from validation errors.
  • Clarify that caller-supplied JSON schema mappings receive lightweight top-level checks rather than comprehensive JSON Schema enforcement.
  • Add streaming, approval, middleware ordering, validation, and security regression coverage, and update the function-calling-loop specification.
• What is the impact of these changes?
  • Function middleware can repair provider/model argument deviations before final schema validation.
  • Middleware that calls call_next() observes normalized arguments afterward.
  • Approval-bound argument changes require one additional approval round trip rather than executing under stale authority.
  • Pydantic-backed tools retain recursive validation; mapping-backed schemas remain declaration-oriented and are documented as unsuitable for security enforcement.
• What do you want reviewers to focus on?
  • The raw-arguments → middleware → final-validation ordering.
  • Replacement approval identity and exactly-once execution across streaming and non-streaming paths.
  • FIDES non-disclosure and fail-closed behavior when argument mutation occurs after policy inspection.

Related Issue

Fixes #7588

No other open pull request was found for this issue.

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 is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• 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.

[Copilot]

🟡 Changes recommended

Validation errors can still expose resolved secrets, and short-circuited middleware can bypass replacement approval checks.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Moves Python function argument validation after middleware, enabling argument repair while retaining approval and security controls.

Changes:

• Adds pre-validation middleware argument repair.
• Adds replacement approvals and post-security mutation safeguards.
• Expands regression tests and documentation.

File summaries

File	Description
python/samples/02-agents/tools/README.md	Clarifies schema-validation limitations.
python/samples/02-agents/tools/function_tool_with_explicit_schema.py	Documents safe schema choices.
python/packages/core/tests/test_security.py	Tests security and redaction behavior.
python/packages/core/tests/core/test_function_invocation_logic.py	Tests middleware repair and approvals.
python/packages/core/agent_framework/security.py	Snapshots security-inspected arguments.
python/packages/core/agent_framework/_tools.py	Implements deferred validation and approval checks.
python/packages/core/agent_framework/_middleware.py	Documents raw argument middleware semantics.
docs/specs/004-python-function-calling-loop.md	Updates normative function-loop behavior.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 3
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (1 commit(s)): eef825f19db4
Model: gpt-5.6-sol-fast

Overview

The change establishes a clear raw-arguments-to-middleware-to-final-validation flow and adds strong regression coverage for ordinary repair, short-circuiting, error separation, replacement approvals, and hidden-value redaction. The new approval and security snapshots correctly catch plainly unequal mutations, but their Python equality checks miss JSON type changes, and final Pydantic transformations can still occur after policy inspection. Moving raw mappings onto the existing public arguments attribute also breaks current middleware that relies on the previously documented validated-model contract.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
4 verified findings remained after source verification (2 high, 2 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_tools.py

[github-actions]

MAF Automated Review — Iteration 2

Result: Findings reported
Scope: 12 net-new commit(s): 5a8cef940916, 4d173b24007d, c15246c0ae71, eddccc474c07, 3abfddffc556, e4309e5456c4, 5d0560975733, e1c849c4ad1a, c744b16af97b, 4e020838d701, c1f33dfca3b4, a9cbc1d5497b
Model: gpt-5.6-sol-fast

Overview

The PR establishes middleware as a repair seam while preserving final validation, approval replacement, security fail-closed checks, and redacted validation errors. Its strongest guardrails cover invalid-argument repair, short-circuit authorization, exactly-once replacement approval, and boolean-versus-number snapshot comparisons. Residual issues remain in how normalized approved arguments are initially bound, how prepared values are copied, and how exceptional floating-point values are compared for approval and security snapshots.

Reviewed the supplied incremental change set across correctness, security/reliability, architecture, and failure behavior.
4 verified findings remained after source verification (1 high, 3 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: python/packages/core/agent_framework/_tools.py