.NET: Add pending tool approval closure semantics (#7872)

[Shivani . (Shivani767)]

Motivation & Context

When a run is cancelled, refreshed, or otherwise interrupted after the model emits a tool call (or after ToolApprovalRequestContent is surfaced), the session can retain pending approval state with no public, reliable way for the host to enumerate or close it. Separately, ApprovalResponseBindingChatClient cleared the pending bag on any subsequent turn—even an unrelated user message with no approval response—so a restored session could lose binding authority while a dangling FunctionCallContent remained in history (#7862 / #7872).

This PR addresses the triage-sized slice of #7872: stop the silent consume bug and give hosts a public drain/closure path. Moving the FICC loop out of Microsoft.Extensions.AI and adding a configurable auto-drain policy are left for follow-up.

Assigned on the issue to Roger Barreto (@rogerbarreto) — happy to coordinate or close if a maintainer PR supersedes this.

Description & Review Guide

• What are the major changes?

  • Do not clear pending approvals on unrelated turns. ValidateInboundApprovalResponses only consumes bag entries when a matching ToolApprovalResponseContent is bound in the current turn; an ordinary user follow-up leaves pending state intact.
  • Public session helpers in ToolApprovalAgentSessionExtensions:
    • TryGetPendingToolApprovalRequests — enumerate pending approvals (including after session restore).
    • CreatePendingApprovalRejections — drain as explicit rejections the host can send on the next run so FICC can emit terminal FunctionResultContent.
    • ClearPendingToolApprovalRequests — drop bag entries without producing responses (documented as the weaker option).
  • Unit tests covering preserve-on-unrelated-turn, serialize/deserialize round-trip, consume-after-response, reject drain, and clear.

• What is the impact of these changes?

  • Restored sessions no longer silently lose approval binding authority on the next normal user message.
  • Hosts can discover and deliberately close pending approvals without reading private state bag keys.
  • Does not auto-drain on every new user turn (configurable policy still open) and does not cover non-approval dangling FunctionCallContent closure in FICC.

• What do you want reviewers to focus on?

  • Whether leaving pending intact (vs auto-reject) on an unrelated turn is the right default until a configurable policy exists.
  • API naming/placement vs overlapping .NET: expose pending tool approval requests from a restored AgentSession #7867 (TryGetPendingToolApprovalRequests only) — this PR intentionally includes that read API plus drain helpers and the silent-consume fix.

Related Issue

Fixes #7872

Related: #7862, #7867

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

Adds durable pending tool-approval discovery and explicit closure APIs while preserving pending approvals across unrelated turns.

Changes:

• Preserves pending approvals until matching responses arrive.
• Adds APIs to enumerate, reject, or clear pending approvals.
• Adds lifecycle and serialization tests.

Reviewed changes

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

File	Description
ApprovalResponseBindingChatClient.cs	Retains and selectively consumes pending approvals.
ToolApprovalAgentSessionExtensions.cs	Adds public pending-approval session helpers.
ApprovalResponseBindingChatClientTests.cs	Tests preservation, restoration, rejection, and clearing.

---

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

[1448376744 (soul-soft)]

Thanks for the update. I want to double-check one remaining case from #7872.

This PR appears to address pending approvals, but does it also handle ordinary non-approval tool calls that become
dangling when agent.run is cancelled before the function loop drains/completes them?

My concern is that a cancelled run can still leave unresolved FunctionCallContent for normal tools, and the next turn
may proceed without an explicit rejection/closure message for those calls. That seems separate from the approval queue
case.

Is that scenario expected to be fixed in this PR, or should #7872 remain open / be tracked by a follow-up issue?

[Shivani . (Shivani767)]

1448376744 (@soul-soft) Thanks for raising this. You’re right to distinguish the two cases.

My understanding of this PR is that it specifically addresses the lifecycle of pending tool approvals—preserving the approval binding across turns and providing explicit APIs to reject or clear those pending approvals.

The case where a normal (non-approval) tool call becomes dangling because agent.run is cancelled before the function loop completes is a separate lifecycle scenario, and I don’t believe this PR currently guarantees explicit closure/rejection for those calls.

I’ll take a closer look at the cancellation path to confirm whether there is any existing cleanup that covers this case. If it isn’t covered, I agree that #7872 should either remain open or have a follow-up issue tracking the non-approval dangling FunctionCallContent scenario, rather than expanding this PR beyond its intended scope.

[1448376744 (soul-soft)]

Shivani . (@Shivani767)

Thanks for the quick clarification. That answers my concern.

I agree that the closure behavior for cancelled normal tool calls should be handled separately from the pending approval lifecycle covered by this PR.

For the non-approval cancellation case, my current thinking is that the more natural place to handle the cancellation event is at the ChatHistoryProvider level. If the framework supports cancellation
semantics, it will likely be used together with PerServiceCallChatHistoryPersistingChatClient to preserve continuity across the function loop. In that setup, the history provider is the component with the
full persisted message context, so it seems like the right place to apply a consistent closure rule for historical messages, including adding an explicit terminal cancellation/failure result for unresolved
FunctionCallContent.

So I agree with keeping this PR focused on pending approvals, and tracking the non-approval dangling FunctionCallContent cancellation path in #7872 or a follow-up issue.