Python: Add per-tool AgentModeProvider exposure controls

[Eduard van Valkenburg (eavanvalkenburg)]

Motivation & Context

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

This change allows each built-in mode tool to be omitted independently without disabling mode state, per-turn instructions, or external mode-change notifications.

Description & Review Guide

• What are the major changes? Add expose_mode_set and expose_mode_get options to AgentModeProvider, both defaulting to True; conditionally contribute each tool; adapt only built-in guidance so it does not advertise hidden tools; add set_agent_mode(..., notify=False) for agent-invoked replacement tools that already surface their own result; document application-controlled mode replacement through the existing provider, tools, and state-helper APIs; add coverage for all exposure combinations, custom guidance, retained state and notifications, and a harness replacement tool.
• What is the impact of these changes? Existing applications keep identical defaults. Applications can hide either or both provider tools while preserving the mode subsystem and can connect replacement tools to the same session-backed state with get_agent_mode and set_agent_mode.
• What do you want reviewers to focus on? Whether the exposure-aware built-in guidance remains clear when mode_set is hidden, while custom instructions and mode_instructions remain untouched.

Related Issue

Fixes #7221

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 the title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Replacement setters currently trigger notifications intended only for external mode changes.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

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

Changes:

• Adds expose_mode_set and expose_mode_get.
• Adapts built-in guidance for hidden tools.
• Adds documentation and exposure/state tests.

File summaries

File	Description
python/packages/core/agent_framework/_harness/_mode.py	Implements tool exposure controls.
python/packages/core/tests/core/test_harness_mode.py	Tests exposure combinations and retained state.
python/packages/core/tests/core/test_harness_agent.py	Tests a replacement mode tool.
python/samples/02-agents/context_providers/README.md	Documents application-controlled modes.

Review details

• Files reviewed: 4/4 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: No findings
Scope: full PR (1 commit(s)): e108e1f5afcf
Model: gpt-5.6-sol-fast

Overview

This PR adds independent, default-on controls for exposing the built-in mode setter and getter while retaining mode state, workflow instructions, and external-change notifications. The four-way exposure tests, replacement-tool integration test, custom-guidance preservation checks, and session-scoped state lifecycle provide strong coverage of the intended contract. No Critical, High, or Medium defect was established.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
No publishable findings remained after source verification for this scope.

[github-actions]

MAF Automated Review — Iteration 2

Result: Findings reported
Scope: full PR (2 commit(s)): 7672c2c027f7, 9ba24344ad5e
Model: gpt-5.6-sol-fast

Overview

The change independently gates the two built-in mode tools while preserving session-backed mode state, exposure-aware default guidance, and external-change notifications. The four exposure combinations, custom guidance behavior, state persistence, and replacement-tool integration have focused tests, and the state remains fixed-key and session-local. One uncommon ordering remains: a no-notification replacement update can retain an earlier queued external-change marker and inject a redundant user-role notification on the next run.

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: python/packages/core/agent_framework/_harness/_mode.py