Python: Correlate AG-UI confirm_changes snapshots by call id

[eavanvalkenburg]

Motivation & Context

AG-UI confirm_changes uses a synthetic confirmation call id. Snapshot cleanup can therefore miss the original
tool result or combine unrelated results when several calls are present.

Description & Review Guide

• What are the major changes?
  • Resolve the synthetic confirmation to its original function_call_id.
  • Replace the approval payload with only the matching result.
  • Require a real result before recording an accepted confirmation; clean rejection explicitly.
  • Treat malformed or non-list confirmation metadata as inert.
• What is the impact of these changes?
  • Completed approval-gated changes remain completed in replayed snapshots.
  • Unrelated tool results cannot leak into the confirmation message.
  • Blocked or invalid accepted approvals cannot be recorded as successful side effects.
  • Malformed snapshot metadata does not trigger guessed correlation.
• What do you want reviewers to focus on?
  • Exact original-call correlation when multiple results exist.
  • Fallback behavior and malformed metadata handling.

Related Issue

Fixes #6828

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]

Pull request overview

This PR fixes AG-UI confirm_changes snapshot cleanup so the synthetic confirmation tool call is correlated back to the original function_call_id, preventing unrelated tool results from being substituted/concatenated when multiple tool results exist. It also adds deterministic fallbacks for accepted/declined/missing-result cases and ensures malformed confirmation metadata is treated as inert.

Changes:

• Add _confirm_changes_target_call_id to resolve a confirm_changes tool result’s synthetic call id back to its original call id (via explicit payload or parsed tool-call arguments).
• Update _clean_resolved_approvals_from_snapshot to replace only the matching original tool result (or apply deterministic fallbacks), rather than potentially combining unrelated results.
• Add focused unit tests and update AG-UI documentation/spec coverage to lock in the expected behavior.

Reviewed changes

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

File	Description
python/packages/ag-ui/agent_framework_ag_ui/_agent_run.py	Implements original-call correlation for confirm_changes snapshot cleanup and deterministic fallbacks.
python/packages/ag-ui/tests/ag_ui/test_confirm_changes_snapshot.py	Adds regressions for multi-result correlation, explicit payload correlation, rejection/missing-result fallbacks, and malformed metadata handling.
python/packages/ag-ui/AGENTS.md	Documents the confirm_changes snapshot cleanup invariant (must not concatenate unrelated results).
docs/specs/004-python-function-calling-loop.md	Updates the spec’s invariant/test mapping to include the new confirm_changes snapshot coverage.

[github-actions]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/ag-ui/agent_framework_ag_ui
_agent_run.py	1147	118	89%	184–191, 238–239, 246, 355, 359, 361, 378, 405–406, 519, 533, 537, 541, 544, 549, 554, 563, 566, 573–579, 612, 624, 635, 638, 673, 727–731, 796, 811, 814, 816, 842, 868–870, 928, 930, 932, 935–939, 953, 961–966, 975–976, 1025–1028, 1039, 1047, 1079, 1094, 1108, 1120, 1150, 1154, 1157, 1159, 1199–1201, 1265, 1271–1272, 1277, 1281–1282, 1480, 1488, 1518, 1522, 1567, 1626, 1656–1657, 1779, 1925, 1985, 2002, 2022–2023, 2030, 2138, 2166, 2174, 2176, 2179, 2185, 2240, 2243, 2253–2254, 2261, 2307
TOTAL	45889	4476	90%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
9472	34 💤	0 ❌	0 🔥	2m 28s ⏱️

[github-actions]

Automated Code Review

Reviewers: 5 | Confidence: 62% | Result: All clear

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

---

Automated review by eavanvalkenburg's agents