Python: Handle provider-invalidated responses

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

Providers do not use terminal response reasons uniformly. A response can stop because of an output limit while still containing a complete, schema-usable local function call, while other provider protocols explicitly invalidate partial response output and require callers to discard it.

The function-invocation loop needs to preserve usable calls by default while giving provider adapters an explicit way to abort calls their protocol invalidated.

Description & Review Guide

• What are the major changes?
  • Add the public ResponseInvalidatedException chat-client signal.
  • Keep generic function invocation independent of finish_reason, including complete calls returned with length.
  • Clear invocation budget state, restore the last valid continuation, and re-raise when a provider invalidates the current response.
  • Apply that signal to documented Anthropic local-tool invalidation cases: non-tool terminal reasons, open tool blocks, missing message_stop, and non-cancellation stream failures.
  • Document the policy in ADR 0041 and the Python function-calling loop specification.
• What is the impact of these changes?
  • Valid, schema-usable calls retain the normal approval, middleware, execution, and continuation flow.
  • Invalidated Anthropic calls cannot create new approvals, execute tool bodies, produce results, trigger another model request, or success-persist partial output.
  • Direct streaming consumers may observe partial call updates; ResponseInvalidatedException explicitly tells them to discard those updates.
• What do you want reviewers to focus on?
  • Exception propagation and cleanup in both response modes, Anthropic local-versus-hosted tool classification, cancellation behavior, and per-service-call persistence.

Related Issue

Supersedes #8305 with a narrower provider-specific design.

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]

🔵 Needs a closer look

Cross-layer streaming, continuation, and persistence semantics warrant final human validation despite strong test coverage.

Pull request overview

Adds provider-specific response invalidation while preserving provider-neutral execution of schema-valid function calls.

Changes:

• Introduces and exports ResponseInvalidatedException.
• Cleans up invocation state and prevents side effects after invalidation.
• Implements Anthropic protocol validation with comprehensive tests and documentation.

File summaries

File	Description
python/packages/core/tests/core/test_function_invocation_logic.py	Tests execution, cleanup, persistence, and continuation behavior.
python/packages/core/tests/core/test_exceptions.py	Tests exception hierarchy and serialization.
python/packages/core/agent_framework/exceptions.py	Defines the invalidation exception.
python/packages/core/agent_framework/_tools.py	Handles invalidation across function-loop modes.
python/packages/core/agent_framework/__init__.pyi	Exposes the typed public API.
python/packages/core/agent_framework/__init__.py	Exposes the runtime public API.
python/packages/anthropic/tests/test_anthropic_client.py	Covers Anthropic terminal and failure scenarios.
python/packages/anthropic/pyproject.toml	Raises the required core version.
python/packages/anthropic/agent_framework_anthropic/_chat_client.py	Detects invalidated Anthropic responses.
python/CODING_STANDARD.md	Documents the exception hierarchy.
docs/specs/004-python-function-calling-loop.md	Defines function-loop invalidation semantics.
docs/decisions/0041-handle-provider-invalidated-responses.md	Records the provider-specific design decision.

Review details

• Files reviewed: 12/12 changed files
• Comments generated: 0
• Review effort level: Balanced (auto)

Note

Copilot is running an experiment and ran this review at Balanced.

---

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

[github-code-quality]

Code Coverage Overview

Languages: Python

Python / code-coverage/python

The overall line coverage in commit 83007f6 in the provider-invalidated... branch is 91%. Line coverage data for the main branch is not yet available.

Show a line coverage summary of the most covered files.

File	main	provider-invalidated... 83007f6	+/-
packages/core/a...ework/_tools.py	—	95%	—
packages/core/a...work/_skills.py	—	95%	—
packages/core/a...rk/_sessions.py	—	95%	—
packages/openai..._chat_client.py	—	94%	—
packages/core/a.../_compaction.py	—	94%	—
packages/core/a...ework/_types.py	—	93%	—
packages/core/a...bservability.py	—	93%	—
packages/core/a...amework/_mcp.py	—	92%	—
packages/ag-ui/...i/_agent_run.py	—	89%	—
packages/core/a...ork/security.py	—	89%	—

---

_{Updated September 15, 2026 14:30 UTC}

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (6 commit(s)): 3a2fc631c24b, e26e4fcf1d9f, 0d6a2ede852f, cff936c2b17b, 536df66bc12a, 819a562d54ba
Model: gpt-5.6-sol-fast

Overview

The PR adds a provider-specific invalidation signal while preserving provider-neutral execution of schema-usable calls, with strong dual-mode tests around side-effect prevention, terminal stream evidence, cancellation, and persistence. Two residual compatibility issues remain: the Anthropic package permits a released core version that lacks the newly imported API, and rollback aliases mutable structured continuation state instead of snapshotting it.

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

Affected areas: python/packages/anthropic/pyproject.toml, python/packages/core/agent_framework/_tools.py