Python: Core: notify agent of external AgentModeProvider mode changes

[eavanvalkenburg]

Description

Follow-up to #5611 (already merged) that addresses reviewer feedback about external mode changes confusing the agent.

When the user changes the mode externally (e.g. via a slash-command handler calling set_agent_mode), the chat history still shows the agent's prior set_mode tool call near the end. Updating only the system instructions wasn't enough — models tend to anchor on the recent tool call and ignore the new mode. The reviewer's example:

system: mode is plan
toolcall: mode is execute

The agent typically thought it was still in execute mode.

This PR aligns with the existing .NET AgentModeProvider behavior:

• set_agent_mode (the public helper used by external callers) now records the previous mode in provider state when the mode actually changes.
• On the next before_run, the provider pops that flag and injects a user-role notification message into the context (Mode changed: ... switched from "X" to "Y". You must now adjust your behavior...), so the most recent context unambiguously reflects the current mode.
• The agent-driven set_mode tool bypasses this — it writes current_mode directly so it doesn't trigger a redundant self-notification.

Contribution Checklist

• The code builds clean without any errors or warnings
• I have added tests covering my changes
• I have updated the documentation accordingly

Tests

5 new tests in test_harness_mode.py:

• External change records previous mode; no-op set does not.
• After external change, next run injects exactly one user message and clears the flag.
• Agent-driven set_mode tool does not queue a notification.
• Subsequent runs without further external changes do not re-inject.

[moonbox3]

Python Test Coverage Report •

File	Stmts	Miss	Cover	Missing
packages/core/agent_framework/_harness
_mode.py	102	1	99%	68
TOTAL	32269	3711	88%

Python Unit Test Overview

Tests	Skipped	Failures	Errors	Time
6299	30 💤	0 ❌	0 🔥	1m 41s ⏱️

[Copilot]

Pull request overview

This PR updates the Python AgentModeProvider (Agent Harness) so that externally-triggered mode changes (e.g., via set_agent_mode from a slash-command handler) are surfaced to the model as a fresh user-role notification message on the next run, preventing the model from anchoring on a recent set_mode tool call in the prior chat history.

Changes:

• Track external mode transitions by recording the previous mode in session state when set_agent_mode actually changes the mode.
• Inject a one-time user notification message during the next AgentModeProvider.before_run, then clear the marker so it won’t repeat.
• Add unit tests validating the state marker behavior, one-time injection, and that agent-driven set_mode does not queue notifications.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
python/packages/core/agent_framework/_harness/_mode.py	Records previous mode for external changes and injects a one-time user notification message on the next run; agent tool path bypasses the notification marker.
python/packages/core/tests/core/test_harness_mode.py	Adds tests covering the external-change marker, no-op behavior, single injection + clearing, and no reinjection on subsequent runs.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 90% | Result: All clear

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

---

Automated review by eavanvalkenburg's agents