[dotnet-port-api] Align agentmode session helpers

[github-actions]

Summary

Add explicit session-first AgentMode helper APIs by introducing (*agentmode.Provider).GetModeForSession and SetModeForSession, then keep the existing option-based GetMode and SetMode methods as compatibility wrappers.

This ports the narrow public API portion of the upstream AgentMode graduation work so Go callers can read and update mode state directly from an *agent.Session, matching the current .NET usage model without forcing a breaking rename of the existing Go helpers.

Upstream reference:

• microsoft/agent-framework@e57f046 - Graduate mode and todo providers
  microsoft/agent-framework@e57f046

Ported .NET PRs

• .NET: [BREAKING] Graduate todo and agent mode providers out of experimental agent-framework#7052 - graduate mode and todo providers

Breaking Changes

No.

Tests and Examples

• go test ./agent/harness/agentmode -count=1
• go test ./agent/... -count=1
• Added focused coverage for GetModeForSession and SetModeForSession
• Updated the external mode-change tests to exercise the new session-based helpers
• Updated docs/dotnet-go-sdk-feature-comparison.md
• No examples changed

Notes

• The existing option-based GetMode and SetMode APIs remain available and now delegate to the new session-first helpers.
• This PR intentionally ports only the AgentMode session-helper surface from .NET: [BREAKING] Graduate todo and agent mode providers out of experimental agent-framework#7052; broader todo-provider graduation work was left out to keep the nightly change narrowly scoped.
• Existing workflow items already cover nearby tool-approval and workflow-behavior changes, so they were intentionally not bundled here.
• Upstream head inspected during candidate selection was upstream-agent-framework/main at 7c6b1e975.

Generated by .NET to Go API Porting Agent · 876.6 AIC · ⌖ 39 AIC · ⊞ 21.7K · ◷

---

Note

This was originally intended as a pull request, but GitHub Actions is not permitted to create or approve pull requests in this repository.
The changes have been pushed to branch dotnet-port-api-agentmode-session-helpers-20260720-9d856a177c90b0db.

Click here to create the pull request

To fix the permissions issue, go to Settings → Actions → General and enable Allow GitHub Actions to create and approve pull requests. See also: gh-aw FAQ

Show patch preview (321 of 321 lines)

From 7884dd84ff74f8dabd6f31b50dfbd62280a26bec Mon Sep 17 00:00:00 2001
From: "github-actions[bot]" <github-actions[bot]@users.noreply.github.com>
Date: Mon, 20 Jul 2026 06:35:06 +0000
Subject: [PATCH] [dotnet-port-api] Align agentmode session helpers

Port the AgentMode session-helper parity from microsoft/agent-framework#7052 by adding explicit session-based helper methods while preserving the existing option-based helpers as compatibility wrappers.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 agent/harness/agentmode/agentmode.go      | 102 ++++++++++++----------
 agent/harness/agentmode/agentmode_test.go |  55 ++++++++++--
 docs/dotnet-go-sdk-feature-comparison.md  |   4 +-
 3 files changed, 107 insertions(+), 54 deletions(-)

diff --git a/agent/harness/agentmode/agentmode.go b/agent/harness/agentmode/agentmode.go
index 1496d9542..3b7dc1f07 100644
--- a/agent/harness/agentmode/agentmode.go
+++ b/agent/harness/agentmode/agentmode.go
@@ -184,8 +184,12 @@ type Provider struct {
 // own, so a runtime cleanup deletes the entry once the session is collected,
 // keeping the registry from growing unbounded.
 func (p *Provider) getSessionLock(opts []agent.Option) *sync.Mutex {
-	session, ok := agent.GetOption(opts, agent.WithSession)
-	if !ok || session == nil {
+	session, _ := agent.GetOption(opts, agent.WithSession)
+	return p.getSessionLockForSession(session)
+}
+
+func (p *Provider) getSessionLockForSession(session *agent.Session) *sync.Mutex {
+	if session == nil {
 		return &p.nullSessionLock
 	}
 	key := weak.Make(session)
@@ -204,17 +208,8 @@ func (p *Provider) getSessionLock(opts []agent.Option) *sync.Mutex {
 	return actual.(*sync.Mutex)
 }
 
-func (p *Provider) Invoking(ctx context.Context, invoking agent.InvokingContext) ([]*message.Message, []agent.Option, error) {
-	return p.provider.Invoking(ctx, invoking)
-}
-
-func (p *Provider) Invoked(ctx context.Context, invoked agent.InvokedContext) error {
-	return p.provider.Invoked(ctx
... (truncated)