.NET: Add per-tool AgentModeProvider controls

[westey (westey-m)]

Motivation & Context

Applications can retain AgentModeProvider state and workflow guidance while supplying their own mode-change UI or function tool, but the .NET provider currently always exposes both mode_set and mode_get. This gives the model duplicate mode authorities when an application provides a replacement setter.

This change allows each built-in mode tool to be disabled independently without disabling mode state, per-turn instructions, helper APIs, or external mode-change notifications. Replacement function tools can reuse SetModeAsync while suppressing redundant notifications already conveyed through the tool result.

Description & Review Guide

• What are the major changes? Add DisableModeSetTool and DisableModeGetTool options, both defaulting to false; conditionally contribute each built-in tool; use internal templates so default guidance does not advertise disabled tools; add a backward-compatible SetModeAsync overload with required disableNotification; clear stale pending notifications when suppression is requested; and add coverage for all exposure combinations, custom guidance, retained state, notifications, and API behavior.
• What is the impact of these changes? Existing applications retain both tools and current notification behavior by default. Applications can hide either or both built-in tools while preserving the mode subsystem and can connect a replacement function tool to the same session-backed state without producing a redundant notification on the next invocation.
• What do you want reviewers to focus on? Whether the default guidance remains coherent for every tool combination, whether the SetModeAsync overload preserves compatibility, and whether suppressed updates correctly clear stale pending notifications.

Related Issue

Related to #7221. This is the .NET counterpart to #8450, which implemented the Python behavior and closed the original issue. No separate open .NET issue or duplicate PR was found.

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

The new overload makes existing positional default-literal calls ambiguous, creating an unintended source-breaking change.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds independent controls for AgentModeProvider tools while retaining mode state, guidance, and notifications.

Changes:

• Adds per-tool disable options and exposure-aware instructions.
• Adds notification suppression for external mode updates.
• Expands tests and public API baselines.

File summaries

File	Description
AgentModeProvider.cs	Implements tool controls, guidance, and notification suppression.
AgentModeProviderOptions.cs	Adds tool-disable options.
AgentModeProviderTests.cs	Tests exposure combinations and notifications.
PublicAPI/net10.0/PublicAPI.Unshipped.txt	Records new net10.0 APIs.
PublicAPI/net9.0/PublicAPI.Unshipped.txt	Records new net9.0 APIs.
PublicAPI/net8.0/PublicAPI.Unshipped.txt	Records new net8.0 APIs.
PublicAPI/netstandard2.0/PublicAPI.Unshipped.txt	Records new netstandard2.0 APIs.
PublicAPI/net472/PublicAPI.Unshipped.txt	Records new net472 APIs.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 1
• 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)): 6589bafa15b7
Model: gpt-5.6-sol-fast

Overview

The .NET implementation independently gates both built-in tools, updates only default guidance, and preserves mode state and notification behavior; the added tests cover all exposure combinations and stale-notification suppression. One source-compatibility gap remains: the new Boolean overload makes an existing positional default cancellation-token call ambiguous at compile time.

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

Affected areas: dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs