.NET: Add FileAccessProvdider and concurrency fix for FileMemoryProvider (#5583)

* Add FileAccessProvdider and concurrency fix for FileMemoryProvider

* Address PR comments

dotnet/Directory.Packages.props

@@ -86,6 +86,7 @@
     <PackageVersion Include="Microsoft.Extensions.Configuration.UserSecrets" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="10.0.6" />
+    <PackageVersion Include="Microsoft.Extensions.FileSystemGlobbing" Version="10.0.6" />
     <PackageVersion Include="Microsoft.Extensions.Hosting" Version="10.0.1" />
     <PackageVersion Include="Microsoft.Extensions.Http.Resilience" Version="10.0.0" />
     <PackageVersion Include="Microsoft.Extensions.Logging" Version="10.0.1" />
@@ -135,6 +136,8 @@
     <PackageVersion Include="Microsoft.Azure.Functions.Worker.Sdk" Version="2.0.7" />
     <!-- Redis -->
     <PackageVersion Include="StackExchange.Redis" Version="2.10.1" />
+    <!-- Console UX -->
+    <PackageVersion Include="Spectre.Console" Version="0.49.1" />
     <!-- Test -->
     <PackageVersion Include="FluentAssertions" Version="8.8.0" />
     <PackageVersion Include="Microsoft.AspNetCore.TestHost" Condition="'$(TargetFramework)' == 'net8.0'" Version="8.0.22" />

dotnet/agent-framework-dotnet.slnx

@@ -117,6 +117,13 @@
     <Project Path="samples/02-agents/AgentSkills/Agent_Step04_MixedSkills/Agent_Step04_MixedSkills.csproj" />
     <Project Path="samples/02-agents/AgentSkills/Agent_Step05_SkillsWithDI/Agent_Step05_SkillsWithDI.csproj" />
   </Folder>
+  <Folder Name="/Samples/02-agents/Harness/">
+    <File Path="samples/02-agents/Harness/README.md" />
+    <Project Path="samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj" />
+    <Project Path="samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj" />
+  </Folder>
   <Folder Name="/Samples/02-agents/AGUI/Step05_StateManagement/">
     <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Client/Client.csproj" />
     <Project Path="samples/02-agents/AGUI/Step05_StateManagement/Server/Server.csproj" />

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ICommandHandler.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles a console command (e.g., /todos, /mode). Command handlers are checked
+/// in order before user input is sent to the agent. The first handler that
+/// accepts the input prevents further handlers from being checked.
+/// </summary>
+public interface ICommandHandler
+{
+    /// <summary>
+    /// Gets the help text for this command, displayed in the console header.
+    /// Returns <see langword="null"/> if the command is not currently available.
+    /// </summary>
+    /// <returns>Help text like <c>"/todos (show todo list)"</c>, or <see langword="null"/>.</returns>
+    string? GetHelpText();
+
+    /// <summary>
+    /// Attempts to handle the given user input.
+    /// </summary>
+    /// <param name="input">The raw user input string.</param>
+    /// <param name="session">The current agent session.</param>
+    /// <returns><see langword="true"/> if this handler handled the input; <see langword="false"/> otherwise.</returns>
+    bool TryHandle(string input, AgentSession session);
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/ModeCommandHandler.cs

@@ -0,0 +1,69 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/mode</c> command to display or switch the current agent mode.
+/// </summary>
+internal sealed class ModeCommandHandler : ICommandHandler
+{
+    private readonly AgentModeProvider? _modeProvider;
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ModeCommandHandler"/> class.
+    /// </summary>
+    /// <param name="modeProvider">The mode provider, or <see langword="null"/> if not available.</param>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public ModeCommandHandler(AgentModeProvider? modeProvider, IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        this._modeProvider = modeProvider;
+        this._modeColors = modeColors;
+    }
+
+    /// <inheritdoc/>
+    public string? GetHelpText() => this._modeProvider is not null ? "/mode [plan|execute] (show or switch mode)" : null;
+
+    /// <inheritdoc/>
+    public bool TryHandle(string input, AgentSession session)
+    {
+        if (!input.StartsWith("/mode ", StringComparison.OrdinalIgnoreCase) && !input.Equals("/mode", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._modeProvider is null)
+        {
+            System.Console.WriteLine("AgentModeProvider is not available.");
+            return true;
+        }
+
+        string[] parts = input.Split(' ', 2, StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries);
+        if (parts.Length < 2)
+        {
+            string current = this._modeProvider.GetMode(session);
+            System.Console.WriteLine($"\n  Current mode: {current}\n");
+            return true;
+        }
+
+        string newMode = parts[1];
+
+        try
+        {
+            this._modeProvider.SetMode(session, newMode);
+            System.Console.ForegroundColor = ConsoleWriter.GetModeColor(newMode, this._modeColors);
+            System.Console.WriteLine($"\n  Switched to {newMode} mode.\n");
+            System.Console.ResetColor();
+        }
+        catch (ArgumentException ex)
+        {
+            System.Console.ForegroundColor = ConsoleColor.Red;
+            System.Console.WriteLine($"\n  {ex}\n");
+            System.Console.ResetColor();
+        }
+
+        return true;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Commands/TodoCommandHandler.cs

@@ -0,0 +1,66 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+
+namespace Harness.Shared.Console.Commands;
+
+/// <summary>
+/// Handles the <c>/todos</c> command to display the current todo list.
+/// </summary>
+internal sealed class TodoCommandHandler : ICommandHandler
+{
+    private readonly TodoProvider? _todoProvider;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TodoCommandHandler"/> class.
+    /// </summary>
+    /// <param name="todoProvider">The todo provider, or <see langword="null"/> if not available.</param>
+    public TodoCommandHandler(TodoProvider? todoProvider)
+    {
+        this._todoProvider = todoProvider;
+    }
+
+    /// <inheritdoc/>
+    public string? GetHelpText() => this._todoProvider is not null ? "/todos (show todo list)" : null;
+
+    /// <inheritdoc/>
+    public bool TryHandle(string input, AgentSession session)
+    {
+        if (!input.Equals("/todos", StringComparison.OrdinalIgnoreCase))
+        {
+            return false;
+        }
+
+        if (this._todoProvider is null)
+        {
+            System.Console.WriteLine("TodoProvider is not available.");
+            return true;
+        }
+
+        var todos = this._todoProvider.GetAllTodos(session);
+        if (todos.Count == 0)
+        {
+            System.Console.WriteLine("\n  No todos yet.\n");
+            return true;
+        }
+
+        System.Console.WriteLine();
+        System.Console.WriteLine("  ── Todo List ──");
+        foreach (var item in todos)
+        {
+            string status = item.IsComplete ? "✓" : "○";
+            System.Console.ForegroundColor = item.IsComplete ? ConsoleColor.DarkGray : ConsoleColor.White;
+            System.Console.Write($"  [{status}] #{item.Id} {item.Title}");
+            if (!string.IsNullOrWhiteSpace(item.Description))
+            {
+                System.Console.Write($" — {item.Description}");
+            }
+
+            System.Console.WriteLine();
+        }
+
+        System.Console.ResetColor();
+        System.Console.WriteLine();
+        return true;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/ConsoleWriter.cs

@@ -0,0 +1,278 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Spectre.Console;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Centralizes all console output and spinner management for the harness console.
+/// Observers write through this class so the spinner is automatically paused before output.
+/// </summary>
+public sealed class ConsoleWriter : IDisposable
+{
+    private readonly Spinner _spinner = new();
+    private readonly IReadOnlyDictionary<string, ConsoleColor>? _modeColors;
+
+    private bool _lastWasText;
+    private bool _hasReceivedAnyText;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ConsoleWriter"/> class.
+    /// </summary>
+    /// <param name="modeColors">Optional mapping of mode names to console colors.</param>
+    public ConsoleWriter(IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        this._modeColors = modeColors;
+    }
+
+    /// <summary>
+    /// Gets or sets the current agent mode (e.g., "plan", "execute").
+    /// Used to determine the console color for mode-prefixed output.
+    /// </summary>
+    public string? CurrentMode { get; set; }
+
+    /// <summary>
+    /// Writes the agent response header (e.g., "[plan] Agent: ") and starts the spinner.
+    /// </summary>
+    public void WriteResponseHeader()
+    {
+        if (this.CurrentMode is not null)
+        {
+            System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+            System.Console.Write($"\n[{this.CurrentMode}] Agent: ");
+        }
+        else
+        {
+            System.Console.Write("\nAgent: ");
+        }
+
+        this._lastWasText = true;
+        this._hasReceivedAnyText = false;
+        this._spinner.Start();
+    }
+
+    /// <summary>
+    /// Writes informational output with automatic prefix spacing, without a trailing newline.
+    /// Use when continuation content will be appended on the same line.
+    /// </summary>
+    /// <param name="text">The informational text to write (without leading newline/indent — added automatically).</param>
+    /// <param name="color">Optional console color for the text.</param>
+    public async Task WriteInfoAsync(string text, ConsoleColor? color = null)
+    {
+        await this.WriteInfoCoreAsync(text, color, newLine: false);
+    }
+
+    /// <summary>
+    /// Writes informational output with automatic prefix spacing, followed by a newline.
+    /// </summary>
+    /// <param name="text">The informational text to write (without leading newline/indent — added automatically).</param>
+    /// <param name="color">Optional console color for the text.</param>
+    public async Task WriteInfoLineAsync(string text, ConsoleColor? color = null)
+    {
+        await this.WriteInfoCoreAsync(text, color, newLine: true);
+    }
+
+    private async Task WriteInfoCoreAsync(string text, ConsoleColor? color, bool newLine)
+    {
+        await this._spinner.StopAsync();
+
+        string prefix = this._lastWasText ? "\n\n  " : "  ";
+        this._lastWasText = false;
+
+        System.Console.ForegroundColor = color ?? GetModeColor(this.CurrentMode, this._modeColors);
+
+        if (newLine)
+        {
+            System.Console.WriteLine(prefix + text);
+        }
+        else
+        {
+            System.Console.Write(prefix + text);
+        }
+
+        System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+
+        this._spinner.Start();
+    }
+
+    /// <summary>
+    /// Writes text output from the agent, managing line break state.
+    /// Ensures a newline is written before the first text output.
+    /// </summary>
+    /// <param name="text">The text to write.</param>
+    /// <param name="color">Optional console color override for this text.</param>
+    public async Task WriteTextAsync(string text, ConsoleColor? color = null)
+    {
+        await this._spinner.StopAsync();
+
+        if (!this._lastWasText)
+        {
+            System.Console.Write("\n");
+            this._lastWasText = true;
+        }
+
+        this._hasReceivedAnyText = true;
+
+        if (color.HasValue)
+        {
+            System.Console.ForegroundColor = color.Value;
+        }
+
+        System.Console.Write(text);
+
+        if (color.HasValue)
+        {
+            System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+        }
+
+        this._spinner.Start();
+    }
+
+    /// <summary>
+    /// Reads a line of input from the console, pausing the spinner while waiting for input.
+    /// Optionally displays a prompt before reading. The prompt is rendered between
+    /// two horizontal rules for visual clarity.
+    /// </summary>
+    /// <param name="prompt">Optional prompt text to display before reading input.</param>
+    /// <param name="promptColor">Optional console color for the prompt text.</param>
+    /// <returns>The line read from the console, or <c>null</c> if no input is available.</returns>
+    public async Task<string?> ReadLineAsync(string? prompt = null, ConsoleColor? promptColor = null)
+    {
+        await this._spinner.StopAsync();
+
+        if (prompt is not null)
+        {
+            System.Console.WriteLine();
+            AnsiConsole.Write(this.CreateModeRule());
+
+            if (promptColor.HasValue)
+            {
+                System.Console.ForegroundColor = promptColor.Value;
+            }
+
+            System.Console.Write($"  {prompt}");
+
+            if (promptColor.HasValue)
+            {
+                System.Console.ForegroundColor = GetModeColor(this.CurrentMode, this._modeColors);
+            }
+        }
+
+        string? input = System.Console.ReadLine();
+
+        if (prompt is not null)
+        {
+            AnsiConsole.Write(this.CreateModeRule());
+        }
+
+        this._lastWasText = false;
+        return input;
+    }
+
+    /// <summary>
+    /// Presents a selection prompt with the given choices, plus an option to type a custom response.
+    /// Uses Spectre.Console <see cref="SelectionPrompt{T}"/> for interactive arrow-key selection.
+    /// </summary>
+    /// <param name="title">The title/question displayed above the selection list.</param>
+    /// <param name="choices">The list of choices to present.</param>
+    /// <returns>The selected choice text, or the custom-typed response.</returns>
+    public async Task<string> ReadSelectionAsync(string title, IList<string> choices)
+    {
+        await this._spinner.StopAsync();
+
+        AnsiConsole.Write(this.CreateModeRule());
+
+        const string FreeformOption = "✏️  Type a custom response...";
+        var allChoices = choices.Concat([FreeformOption]).ToList();
+
+        var prompt = new SelectionPrompt<string>()
+            .Title($"  [bold]{Markup.Escape(title)}[/]")
+            .PageSize(10)
+            .AddChoices(allChoices);
+
+        string selection = AnsiConsole.Prompt(prompt);
+
+        if (selection == FreeformOption)
+        {
+            var textPrompt = new TextPrompt<string>("  [grey]Response:[/]");
+            selection = AnsiConsole.Prompt(textPrompt);
+        }
+
+        AnsiConsole.MarkupLine($"  [dim]→ {Markup.Escape(selection)}[/]");
+        AnsiConsole.Write(this.CreateModeRule());
+
+        this._lastWasText = false;
+        return selection;
+    }
+
+    /// <summary>
+    /// Writes the stream-complete footer (handles "no text response" fallback, resets color).
+    /// </summary>
+    public async Task WriteStreamFooterAsync(bool hasFollowUpMessages)
+    {
+        await this._spinner.StopAsync();
+
+        if (!this._hasReceivedAnyText && !hasFollowUpMessages)
+        {
+            System.Console.ForegroundColor = ConsoleColor.DarkYellow;
+            System.Console.Write("\n  (no text response from agent)");
+        }
+
+        System.Console.ResetColor();
+        System.Console.WriteLine();
+    }
+
+    /// <inheritdoc/>
+    public void Dispose()
+    {
+        this._spinner.Dispose();
+    }
+
+    /// <summary>
+    /// Gets the console color associated with a mode name, using the provided color map.
+    /// </summary>
+    internal static ConsoleColor GetModeColor(string? mode, IReadOnlyDictionary<string, ConsoleColor>? modeColors = null)
+    {
+        if (mode is null)
+        {
+            return ConsoleColor.Gray;
+        }
+
+        if (modeColors is not null && modeColors.TryGetValue(mode, out var color))
+        {
+            return color;
+        }
+
+        return ConsoleColor.Gray;
+    }
+
+    /// <summary>
+    /// Creates a <see cref="Rule"/> styled with the current mode color.
+    /// </summary>
+    internal Rule CreateModeRule()
+    {
+        var spectreColor = ToSpectreColor(GetModeColor(this.CurrentMode, this._modeColors));
+        return new Rule().RuleStyle(new Style(spectreColor));
+    }
+
+    internal static Color ToSpectreColor(ConsoleColor consoleColor) => consoleColor switch
+    {
+        ConsoleColor.Black => Color.Black,
+        ConsoleColor.DarkBlue => Color.Blue,
+        ConsoleColor.DarkGreen => Color.Green,
+        ConsoleColor.DarkCyan => Color.Teal,
+        ConsoleColor.DarkRed => Color.Red,
+        ConsoleColor.DarkMagenta => Color.Purple,
+        ConsoleColor.DarkYellow => Color.Olive,
+        ConsoleColor.Gray => Color.Silver,
+        ConsoleColor.DarkGray => Color.Grey,
+        ConsoleColor.Blue => Color.Blue1,
+        ConsoleColor.Green => Color.Green1,
+        ConsoleColor.Cyan => Color.Aqua,
+        ConsoleColor.Red => Color.Red1,
+        ConsoleColor.Magenta => Color.Fuchsia,
+        ConsoleColor.Yellow => Color.Yellow,
+        ConsoleColor.White => Color.White,
+        _ => Color.Silver,
+    };
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsole.cs

@@ -0,0 +1,214 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Harness.Shared.Console.Commands;
+using Harness.Shared.Console.Observers;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Provides a reusable interactive console loop for running an <see cref="AIAgent"/>
+/// with streaming output, extensible observers, and mode-aware interaction strategies.
+/// </summary>
+public static class HarnessConsole
+{
+    /// <summary>
+    /// Runs an interactive console session with the specified agent.
+    /// Supports streaming output, tool call display, spinner animation,
+    /// optional planning UX with structured output, and the <c>/todos</c> command.
+    /// </summary>
+    /// <param name="agent">The agent to interact with.</param>
+    /// <param name="title">The title displayed in the console header.</param>
+    /// <param name="userPrompt">A short prompt to the user, displayed below the title.</param>
+    /// <param name="options">Optional configuration options for the console session.</param>
+    public static async Task RunAgentAsync(AIAgent agent, string title, string userPrompt, HarnessConsoleOptions? options = null)
+    {
+        options ??= new();
+
+        if (options.EnablePlanningUx
+            && (string.IsNullOrWhiteSpace(options.PlanningModeName) || string.IsNullOrWhiteSpace(options.ExecutionModeName)))
+        {
+            throw new ArgumentException(
+                "When EnablePlanningUx is true, both PlanningModeName and ExecutionModeName must be configured.",
+                nameof(options));
+        }
+
+        System.Console.WriteLine($"=== {title} ===");
+        System.Console.WriteLine(userPrompt);
+
+        var todoProvider = agent.GetService<TodoProvider>();
+        var modeProvider = agent.GetService<AgentModeProvider>();
+
+        // Build command handlers.
+        var commandHandlers = new List<ICommandHandler>
+        {
+            new TodoCommandHandler(todoProvider),
+            new ModeCommandHandler(modeProvider, options.ModeColors),
+        };
+
+        var commands = commandHandlers
+            .Select(h => h.GetHelpText())
+            .Where(t => t is not null)
+            .Append("exit (quit)");
+
+        System.Console.WriteLine($"Commands: {string.Join(", ", commands)}");
+        System.Console.WriteLine();
+
+        AgentSession session = await agent.CreateSessionAsync();
+        using var writer = new ConsoleWriter(options.ModeColors);
+        writer.CurrentMode = modeProvider?.GetMode(session);
+
+        string prompt = BuildUserPrompt(modeProvider, session);
+        string? userInput = await writer.ReadLineAsync(prompt);
+
+        // Main loop to run a command or agent and get the next user command/input.
+        while (!string.IsNullOrWhiteSpace(userInput) && !userInput.Equals("exit", StringComparison.OrdinalIgnoreCase))
+        {
+            // Check command handlers first — first one to handle wins.
+            bool handled = false;
+            foreach (var handler in commandHandlers)
+            {
+                if (handler.TryHandle(userInput, session))
+                {
+                    handled = true;
+                    break;
+                }
+            }
+
+            if (!handled)
+            {
+                await RunAgentTurnAsync(agent, session, modeProvider, options, writer, userInput);
+            }
+
+            writer.CurrentMode = modeProvider?.GetMode(session);
+            prompt = BuildUserPrompt(modeProvider, session);
+            userInput = await writer.ReadLineAsync(prompt);
+        }
+
+        System.Console.ResetColor();
+        System.Console.WriteLine("Goodbye!");
+    }
+
+    /// <summary>
+    /// Runs one or more agent invocations for a single user turn, using the current
+    /// observers. Re-invokes automatically for tool approvals and mode-driven follow-ups
+    /// (e.g., planning clarification loops).
+    /// </summary>
+    private static async Task RunAgentTurnAsync(
+        AIAgent agent,
+        AgentSession session,
+        AgentModeProvider? modeProvider,
+        HarnessConsoleOptions options,
+        ConsoleWriter writer,
+        string userInput)
+    {
+        IList<ChatMessage>? nextMessages = [new ChatMessage(ChatRole.User, userInput)];
+
+        while (nextMessages is not null)
+        {
+            // Build observers for this invocation (may change between iterations due to mode changes).
+            var observers = CreateObservers(options, modeProvider, session);
+
+            // Build run options — observers may inject ResponseFormat, etc.
+            var runOptions = new AgentRunOptions();
+            foreach (var observer in observers)
+            {
+                observer.ConfigureRunOptions(runOptions);
+            }
+
+            // Stream the response, fanning out to all observers.
+            writer.CurrentMode = modeProvider?.GetMode(session);
+            writer.WriteResponseHeader();
+
+            try
+            {
+                await foreach (var update in agent.RunStreamingAsync(nextMessages, session, runOptions))
+                {
+                    // Update mode color if the mode changed during streaming.
+                    if (modeProvider is not null)
+                    {
+                        string currentMode = modeProvider.GetMode(session);
+                        if (currentMode != writer.CurrentMode)
+                        {
+                            writer.CurrentMode = currentMode;
+                        }
+                    }
+
+                    foreach (var content in update.Contents)
+                    {
+                        foreach (var observer in observers)
+                        {
+                            await observer.OnContentAsync(writer, content);
+                        }
+                    }
+
+                    if (!string.IsNullOrEmpty(update.Text))
+                    {
+                        foreach (var observer in observers)
+                        {
+                            await observer.OnTextAsync(writer, update.Text);
+                        }
+                    }
+                }
+            }
+            catch (Exception ex)
+            {
+                await writer.WriteInfoLineAsync($"❌ Stream error: {ex.GetType().Name}:\n{ex}", ConsoleColor.Red);
+            }
+
+            // Collect messages from all observers.
+            var combinedMessages = new List<ChatMessage>();
+            bool hasObserverMessages = false;
+            foreach (var observer in observers)
+            {
+                var messages = await observer.OnStreamCompleteAsync(writer, agent, session, options);
+                if (messages is { Count: > 0 })
+                {
+                    combinedMessages.AddRange(messages);
+                    hasObserverMessages = true;
+                }
+            }
+
+            await writer.WriteStreamFooterAsync(hasFollowUpMessages: hasObserverMessages);
+            nextMessages = combinedMessages.Count > 0 ? combinedMessages : null;
+        }
+    }
+
+    private static List<ConsoleObserver> CreateObservers(HarnessConsoleOptions options, AgentModeProvider? modeProvider, AgentSession session)
+    {
+        var observers = new List<ConsoleObserver>
+        {
+            new ToolCallDisplayObserver(),
+            new ToolApprovalObserver(),
+            new ErrorDisplayObserver(),
+            new ReasoningDisplayObserver(),
+            new UsageDisplayObserver(options.MaxContextWindowTokens, options.MaxOutputTokens),
+        };
+
+        // Add the appropriate output observer based on the current mode.
+        if (options.EnablePlanningUx
+            && modeProvider is not null
+            && string.Equals(modeProvider.GetMode(session), options.PlanningModeName, StringComparison.OrdinalIgnoreCase))
+        {
+            observers.Add(new PlanningOutputObserver(modeProvider));
+        }
+        else
+        {
+            observers.Add(new TextOutputObserver());
+        }
+
+        return observers;
+    }
+
+    private static string BuildUserPrompt(AgentModeProvider? modeProvider, AgentSession session)
+    {
+        if (modeProvider is not null)
+        {
+            string mode = modeProvider.GetMode(session);
+            return $"[{mode}] You: ";
+        }
+
+        return "You: ";
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/HarnessConsoleOptions.cs

@@ -0,0 +1,52 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// Configuration options for <see cref="HarnessConsole"/>.
+/// </summary>
+public class HarnessConsoleOptions
+{
+    /// <summary>
+    /// Gets or sets the optional maximum context window size in tokens.
+    /// When set, token usage is displayed as a percentage of the budget.
+    /// </summary>
+    public int? MaxContextWindowTokens { get; set; }
+
+    /// <summary>
+    /// Gets or sets the optional maximum output tokens.
+    /// Used with <see cref="MaxContextWindowTokens"/> to show input/output budget breakdown.
+    /// </summary>
+    public int? MaxOutputTokens { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether the planning UX is enabled.
+    /// When <see langword="true"/> and the agent is in the mode specified by <see cref="PlanningModeName"/>,
+    /// the console uses structured output to present clarification questions and approval requests
+    /// instead of streaming free-form text.
+    /// </summary>
+    /// <value>Defaults to <see langword="false"/>.</value>
+    public bool EnablePlanningUx { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the agent mode that activates the planning UX.
+    /// Must be set when <see cref="EnablePlanningUx"/> is <see langword="true"/>.
+    /// </summary>
+    public string? PlanningModeName { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the agent mode to switch to when the user approves a plan.
+    /// Must be set when <see cref="EnablePlanningUx"/> is <see langword="true"/>.
+    /// </summary>
+    public string? ExecutionModeName { get; set; }
+
+    /// <summary>
+    /// Gets or sets a mapping of agent mode names to console colors.
+    /// When a mode is not found in this dictionary, the default color (<see cref="ConsoleColor.Gray"/>) is used.
+    /// </summary>
+    public Dictionary<string, ConsoleColor> ModeColors { get; set; } = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["plan"] = ConsoleColor.Cyan,
+        ["execute"] = ConsoleColor.Green,
+    };
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Harness_Shared_Console.csproj

@@ -0,0 +1,18 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Spectre.Console" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI\Microsoft.Agents.AI.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ConsoleObserver.cs

@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Abstract base class for console observers that participate in the agent response
+/// streaming lifecycle. Observers can configure run options, observe streamed content,
+/// and return messages to re-invoke the agent after the stream completes.
+/// All methods have default no-op implementations so subclasses only override what they need.
+/// </summary>
+public abstract class ConsoleObserver
+{
+    /// <summary>
+    /// Configures <see cref="AgentRunOptions"/> before the agent is invoked.
+    /// Override to set options such as <see cref="AgentRunOptions.ResponseFormat"/>.
+    /// </summary>
+    /// <param name="options">The run options to configure.</param>
+    public virtual void ConfigureRunOptions(AgentRunOptions options)
+    {
+    }
+
+    /// <summary>
+    /// Called for each <see cref="AIContent"/> item in the response stream.
+    /// </summary>
+    /// <param name="writer">The console writer for rendering output.</param>
+    /// <param name="content">The content item from the stream.</param>
+    public virtual Task OnContentAsync(ConsoleWriter writer, AIContent content) => Task.CompletedTask;
+
+    /// <summary>
+    /// Called for each text update in the response stream.
+    /// </summary>
+    /// <param name="writer">The console writer for rendering output.</param>
+    /// <param name="text">The text from the update.</param>
+    public virtual Task OnTextAsync(ConsoleWriter writer, string text) => Task.CompletedTask;
+
+    /// <summary>
+    /// Called after the response stream completes. Returns messages to include in the
+    /// next agent invocation, or <see langword="null"/> if no re-invocation is needed.
+    /// </summary>
+    /// <param name="writer">The console writer for rendering output.</param>
+    /// <param name="agent">The agent being interacted with.</param>
+    /// <param name="session">The current agent session.</param>
+    /// <param name="options">The console options.</param>
+    /// <returns>Messages to send to the agent, or <see langword="null"/> if no action is needed.</returns>
+    public virtual Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        ConsoleWriter writer,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options) => Task.FromResult<IList<ChatMessage>?>(null);
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ErrorDisplayObserver.cs

@@ -0,0 +1,31 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays error content (❌) from the response stream.
+/// </summary>
+internal sealed class ErrorDisplayObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is ErrorContent errorContent)
+        {
+            string errorText = $"❌ Error: {errorContent.Message}";
+            if (!string.IsNullOrWhiteSpace(errorContent.ErrorCode))
+            {
+                errorText += $" (code: {errorContent.ErrorCode})";
+            }
+
+            if (!string.IsNullOrWhiteSpace(errorContent.Details))
+            {
+                errorText += $" details: {errorContent.Details}";
+            }
+
+            await writer.WriteInfoLineAsync(errorText, ConsoleColor.Red);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningOutputObserver.cs

@@ -0,0 +1,177 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+using System.Text.Json;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Planning observer that configures structured output, collects streamed text,
+/// and deserializes it as a <see cref="PlanningResponse"/>. Renders clarification
+/// questions and approval prompts, and manages mode switching when the user approves a plan.
+/// </summary>
+internal sealed class PlanningOutputObserver : ConsoleObserver
+{
+    private readonly StringBuilder _textCollector = new();
+    private readonly AgentModeProvider _modeProvider;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="PlanningOutputObserver"/> class.
+    /// </summary>
+    /// <param name="modeProvider">The mode provider for switching modes on approval.</param>
+    public PlanningOutputObserver(AgentModeProvider modeProvider)
+    {
+        this._modeProvider = modeProvider;
+    }
+
+    /// <inheritdoc/>
+    public override void ConfigureRunOptions(AgentRunOptions options)
+    {
+        options.ResponseFormat = ChatResponseFormat.ForJsonSchema<PlanningResponse>();
+    }
+
+    /// <inheritdoc/>
+    public override Task OnTextAsync(ConsoleWriter writer, string text)
+    {
+        // Collect text silently instead of displaying it.
+        this._textCollector.Append(text);
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc/>
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        ConsoleWriter writer,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options)
+    {
+        // Read collected text from our stream observation.
+        string collectedText = this._textCollector.ToString();
+        this._textCollector.Clear();
+
+        if (string.IsNullOrWhiteSpace(collectedText))
+        {
+            return null;
+        }
+
+        // Deserialize the structured response.
+        PlanningResponse? planningResponse;
+        try
+        {
+            planningResponse = JsonSerializer.Deserialize<PlanningResponse>(collectedText);
+        }
+        catch (JsonException ex)
+        {
+            await writer.WriteInfoLineAsync($"❌ Failed to parse planning response: {ex.Message}", ConsoleColor.Red);
+            await writer.WriteInfoLineAsync($"(raw response) {collectedText}", ConsoleColor.DarkYellow);
+            return null;
+        }
+
+        if (planningResponse is null)
+        {
+            await writer.WriteInfoLineAsync("(no structured response from agent)", ConsoleColor.DarkYellow);
+            return null;
+        }
+
+        // Render based on response type.
+        if (planningResponse.Type == PlanningResponseType.Clarification)
+        {
+            return AsUserMessages(await this.RenderClarificationsAndCollectResponsesAsync(writer, planningResponse));
+        }
+
+        if (planningResponse.Type == PlanningResponseType.Approval)
+        {
+            var question = planningResponse.Questions.FirstOrDefault();
+            if (question is null)
+            {
+                await writer.WriteInfoLineAsync("(approval response had no content)", ConsoleColor.DarkYellow);
+                return null;
+            }
+
+            string response = await this.RenderApprovalAndCollectResponseAsync(writer, question, options);
+            if (response == "Approved")
+            {
+                this._modeProvider.SetMode(session, options.ExecutionModeName!);
+
+                await writer.WriteInfoLineAsync($"✅ Switched to {options.ExecutionModeName} mode.",
+                    ConsoleWriter.GetModeColor(options.ExecutionModeName, options.ModeColors));
+            }
+
+            return AsUserMessages(response);
+        }
+
+        await writer.WriteInfoLineAsync($"(unexpected response type: {planningResponse.Type})", ConsoleColor.DarkYellow);
+        return null;
+    }
+
+    private static IList<ChatMessage>? AsUserMessages(string? text) =>
+        text is not null ? [new ChatMessage(ChatRole.User, text)] : null;
+
+    private async Task<string?> RenderClarificationsAndCollectResponsesAsync(ConsoleWriter writer, PlanningResponse response)
+    {
+        var answers = new List<string>();
+
+        foreach (var question in response.Questions)
+        {
+            await writer.WriteInfoLineAsync(string.Empty);
+            await writer.WriteInfoLineAsync(question.Message);
+
+            string? answer;
+            if (question.Choices is { Count: > 0 })
+            {
+                answer = await writer.ReadSelectionAsync(
+                    "Choose an option:",
+                    question.Choices);
+            }
+            else
+            {
+                answer = (await writer.ReadLineAsync("Response: "))?.Trim();
+            }
+
+            if (!string.IsNullOrWhiteSpace(answer))
+            {
+                answers.Add($"Q: {question.Message}\nA: {answer}");
+            }
+        }
+
+        return answers.Count > 0 ? string.Join("\n\n", answers) : null;
+    }
+
+    private async Task<string> RenderApprovalAndCollectResponseAsync(ConsoleWriter writer, PlanningQuestion question, HarnessConsoleOptions options)
+    {
+        await writer.WriteInfoLineAsync(question.Message);
+
+        var choices = new List<string>
+        {
+            "Approve and switch to execute mode",
+            "Suggest changes",
+        };
+
+        string selection = await writer.ReadSelectionAsync("What would you like to do?", choices);
+
+        if (selection == choices[0])
+        {
+            return "Approved";
+        }
+
+        if (selection == choices[1])
+        {
+            string? feedback = await writer.ReadLineAsync(
+                "Your feedback: ",
+                ConsoleWriter.GetModeColor(options.PlanningModeName, options.ModeColors));
+
+            if (string.IsNullOrWhiteSpace(feedback))
+            {
+                // Treat empty feedback as no changes — re-prompt the agent with the plan.
+                return "No changes suggested. Please re-present the plan for approval.";
+            }
+
+            return feedback;
+        }
+
+        // Custom freeform input — treat as suggested changes.
+        return selection;
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningResponse.cs

@@ -0,0 +1,51 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Represents a structured response from the agent while in planning mode.
+/// Used with structured output to enable consistent rendering of clarification
+/// questions and approval requests in the console.
+/// </summary>
+public class PlanningResponse
+{
+    /// <summary>
+    /// Gets or sets the type of planning response.
+    /// </summary>
+    [JsonPropertyName("type")]
+    public required PlanningResponseType Type { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of questions or items to present to the user.
+    /// For clarification, this contains one or more questions (each with choices).
+    /// For approval, this contains exactly one item with the plan summary.
+    /// </summary>
+    [JsonPropertyName("questions")]
+    [Description("For clarifications, this has one or more questions to ask the user (each with choices). For approvals, this has exactly one item containing the plan summary for the user to approve.")]
+    public required List<PlanningQuestion> Questions { get; set; }
+}
+
+/// <summary>
+/// Represents a single question or item within a <see cref="PlanningResponse"/>.
+/// </summary>
+public class PlanningQuestion
+{
+    /// <summary>
+    /// Gets or sets the message to display to the user.
+    /// For clarification, this is the question. For approval, this is the plan summary.
+    /// </summary>
+    [JsonPropertyName("message")]
+    [Description("For clarifications, this has the question that needs to be clarified with the user. For approvals, this would contain a summary of the execution plan that the user needs to approve.")]
+    public required string Message { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of choices for the user to pick from.
+    /// Only used for clarification questions. Null when no predefined choices are offered.
+    /// </summary>
+    [JsonPropertyName("choices")]
+    [Description("For clarifications, this has a list of options that the user can choose from. null for approvals.")]
+    public List<string>? Choices { get; set; }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/PlanningResponseType.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Text.Json.Serialization;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Specifies the type of planning response from the agent.
+/// </summary>
+[JsonConverter(typeof(JsonStringEnumConverter<PlanningResponseType>))]
+public enum PlanningResponseType
+{
+    /// <summary>
+    /// The agent needs clarification and presents options for the user to choose from.
+    /// </summary>
+    [Description("Use this type when you need clarification around the user request and you want to present the user with options to choose from.")]
+    Clarification,
+
+    /// <summary>
+    /// The agent is seeking approval to proceed with execution.
+    /// </summary>
+    [Description("Use this type when you are ready to start execution, but need approval to start executing.")]
+    Approval,
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ReasoningDisplayObserver.cs

@@ -0,0 +1,20 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays reasoning content in dark magenta from the response stream.
+/// </summary>
+internal sealed class ReasoningDisplayObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is TextReasoningContent reasoning && !string.IsNullOrEmpty(reasoning.Text))
+        {
+            await writer.WriteTextAsync(reasoning.Text, ConsoleColor.DarkMagenta);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/TextOutputObserver.cs

@@ -0,0 +1,16 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Streams agent text output directly to the console.
+/// Used in normal (non-planning) mode.
+/// </summary>
+internal sealed class TextOutputObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnTextAsync(ConsoleWriter writer, string text)
+    {
+        await writer.WriteTextAsync(text);
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolApprovalObserver.cs

@@ -0,0 +1,92 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Collects <see cref="ToolApprovalRequestContent"/> items during the response stream,
+/// displays approval-needed notifications inline, and prompts the user for approval
+/// decisions after the stream completes.
+/// </summary>
+internal sealed class ToolApprovalObserver : ConsoleObserver
+{
+    private readonly List<ToolApprovalRequestContent> _approvalRequests = [];
+
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is ToolApprovalRequestContent approvalRequest)
+        {
+            this._approvalRequests.Add(approvalRequest);
+            string toolName = approvalRequest.ToolCall is FunctionCallContent fc
+                ? ToolCallFormatter.Format(fc)
+                : approvalRequest.ToolCall?.ToString() ?? "unknown";
+            await writer.WriteInfoLineAsync($"⚠️ Approval needed: {toolName}", ConsoleColor.Yellow);
+        }
+    }
+
+    /// <inheritdoc/>
+    public override async Task<IList<ChatMessage>?> OnStreamCompleteAsync(
+        ConsoleWriter writer,
+        AIAgent agent,
+        AgentSession session,
+        HarnessConsoleOptions options)
+    {
+        if (this._approvalRequests.Count == 0)
+        {
+            return null;
+        }
+
+        var messages = await PromptForApprovalsAsync(writer, this._approvalRequests);
+        this._approvalRequests.Clear();
+        return messages;
+    }
+
+    private static async Task<List<ChatMessage>?> PromptForApprovalsAsync(ConsoleWriter writer, List<ToolApprovalRequestContent> approvalRequests)
+    {
+        if (approvalRequests.Count == 0)
+        {
+            return null;
+        }
+
+        var responses = new List<AIContent>();
+        foreach (var request in approvalRequests)
+        {
+            string toolName = request.ToolCall is FunctionCallContent fc
+                ? ToolCallFormatter.Format(fc)
+                : request.ToolCall?.ToString() ?? "unknown";
+
+            var choices = new List<string>
+            {
+                "Approve this call",
+                "Always approve this tool (any arguments)",
+                "Always approve this tool with these arguments",
+                "Deny",
+            };
+
+            string selection = await writer.ReadSelectionAsync($"🔐 Tool approval: {toolName}", choices);
+            AIContent response = selection switch
+            {
+                "Always approve this tool (any arguments)" => request.CreateAlwaysApproveToolResponse("User chose to always approve this tool"),
+                "Always approve this tool with these arguments" => request.CreateAlwaysApproveToolWithArgumentsResponse("User chose to always approve this tool with these arguments"),
+                "Deny" => request.CreateResponse(approved: false, reason: "User denied"),
+                _ => request.CreateResponse(approved: true, reason: "User approved"),
+            };
+
+            string action = selection switch
+            {
+                "Always approve this tool (any arguments)" => "✅ Always approved (any args)",
+                "Always approve this tool with these arguments" => "✅ Always approved (these args)",
+                "Deny" => "❌ Denied",
+                _ => "✅ Approved",
+            };
+            await writer.WriteInfoLineAsync($"   {action}", ConsoleColor.DarkGray);
+
+            responses.Add(response);
+        }
+
+        return [new ChatMessage(ChatRole.User, responses)];
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolCallDisplayObserver.cs

@@ -0,0 +1,25 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays tool call notifications (🔧) for <see cref="FunctionCallContent"/>
+/// and <see cref="ToolCallContent"/> items in the response stream.
+/// </summary>
+internal sealed class ToolCallDisplayObserver : ConsoleObserver
+{
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is FunctionCallContent functionCall)
+        {
+            await writer.WriteInfoLineAsync($"🔧 Calling tool: {ToolCallFormatter.Format(functionCall)}...", ConsoleColor.DarkYellow);
+        }
+        else if (content is ToolCallContent toolCall)
+        {
+            await writer.WriteInfoLineAsync($"🔧 Calling tool: {toolCall}...", ConsoleColor.DarkYellow);
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/ToolCallFormatter.cs

@@ -0,0 +1,288 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Text;
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Formats <see cref="FunctionCallContent"/> instances into human-readable strings
+/// for console display.
+/// </summary>
+public static class ToolCallFormatter
+{
+    /// <summary>
+    /// Returns a formatted string for the given tool call, with human-readable
+    /// details for known tools (todos, mode, sub-agents, web tools).
+    /// </summary>
+    /// <param name="call">The function call content to format.</param>
+    /// <returns>A formatted string describing the tool call.</returns>
+    public static string Format(FunctionCallContent call)
+    {
+        string? detail = call.Name switch
+        {
+            // Todo tools
+            "TodoList_Add" => FormatAddTodos(call),
+            "TodoList_Complete" => FormatIdList(call, "ids", "Complete"),
+            "TodoList_Remove" => FormatIdList(call, "ids", "Remove"),
+            "TodoList_GetRemaining" => null,
+            "TodoList_GetAll" => null,
+
+            // Mode tools
+            "AgentMode_Set" => FormatStringArg(call, "mode"),
+            "AgentMode_Get" => null,
+
+            // Sub-agent tools
+            "SubAgents_StartTask" => FormatStartSubTask(call),
+            "SubAgents_WaitForFirstCompletion" => FormatIdList(call, "taskIds", "Wait for"),
+            "SubAgents_GetTaskResults" => FormatSingleId(call, "taskId"),
+            "SubAgents_GetAllTasks" => null,
+            "SubAgents_ContinueTask" => FormatContinueTask(call),
+            "SubAgents_ClearCompletedTask" => FormatSingleId(call, "taskId"),
+
+            // File memory tools
+            "FileMemory_SaveFile" => FormatSaveFile(call),
+            "FileMemory_ReadFile" => FormatStringArg(call, "fileName"),
+            "FileMemory_DeleteFile" => FormatStringArg(call, "fileName"),
+            "FileMemory_ListFiles" => null,
+            "FileMemory_SearchFiles" => FormatSearchFiles(call),
+
+            // External tools
+            "web_search" => FormatStringArg(call, "query"),
+            "DownloadUri" => FormatStringArg(call, "uri"),
+
+            _ => FormatFallback(call),
+        };
+
+        return detail is not null ? $"{call.Name} {detail}" : call.Name;
+    }
+
+    private static string? FormatAddTodos(FunctionCallContent call)
+    {
+        if (call.Arguments?.TryGetValue("todos", out object? todosObj) != true || todosObj is null)
+        {
+            return null;
+        }
+
+        var titles = new List<string>();
+
+        if (todosObj is JsonElement jsonArray && jsonArray.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in jsonArray.EnumerateArray())
+            {
+                string? title = item.TryGetProperty("title", out JsonElement titleElement)
+                    ? titleElement.GetString()
+                    : null;
+
+                if (!string.IsNullOrEmpty(title))
+                {
+                    titles.Add(title);
+                }
+            }
+        }
+
+        if (titles.Count == 0)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder();
+        sb.Append($"({titles.Count} item{(titles.Count == 1 ? "" : "s")})");
+        foreach (string title in titles)
+        {
+            sb.Append($"\n    • {title}");
+        }
+
+        return sb.ToString();
+    }
+
+    private static string? FormatIdList(FunctionCallContent call, string paramName, string verb)
+    {
+        List<int>? ids = GetIntList(call, paramName);
+        if (ids is null || ids.Count == 0)
+        {
+            return null;
+        }
+
+        return $"({verb} #{string.Join(", #", ids)})";
+    }
+
+    private static string? FormatSingleId(FunctionCallContent call, string paramName)
+    {
+        int? id = GetInt(call, paramName);
+        return id.HasValue ? $"(task #{id.Value})" : null;
+    }
+
+    private static string? FormatStartSubTask(FunctionCallContent call)
+    {
+        string? agentName = GetString(call, "agentName");
+        string? description = GetString(call, "description");
+
+        if (agentName is null && description is null)
+        {
+            return null;
+        }
+
+        var sb = new StringBuilder("(");
+        if (agentName is not null)
+        {
+            sb.Append($"agent: {agentName}");
+        }
+
+        if (description is not null)
+        {
+            if (agentName is not null)
+            {
+                sb.Append(", ");
+            }
+
+            sb.Append($"\"{Truncate(description, 60)}\"");
+        }
+
+        sb.Append(')');
+        return sb.ToString();
+    }
+
+    private static string? FormatContinueTask(FunctionCallContent call)
+    {
+        int? taskId = GetInt(call, "taskId");
+        string? text = GetString(call, "text");
+
+        if (!taskId.HasValue)
+        {
+            return null;
+        }
+
+        return text is not null
+            ? $"(task #{taskId.Value}, \"{Truncate(text, 50)}\")"
+            : $"(task #{taskId.Value})";
+    }
+
+    private static string? FormatSaveFile(FunctionCallContent call)
+    {
+        string? fileName = GetString(call, "fileName");
+        string? description = GetString(call, "description");
+
+        if (fileName is null)
+        {
+            return null;
+        }
+
+        return string.IsNullOrEmpty(description)
+            ? $"({fileName})"
+            : $"({fileName}, with description)";
+    }
+
+    private static string? FormatSearchFiles(FunctionCallContent call)
+    {
+        string? pattern = GetString(call, "regexPattern");
+        string? filePattern = GetString(call, "filePattern");
+
+        if (pattern is null)
+        {
+            return null;
+        }
+
+        return string.IsNullOrEmpty(filePattern)
+            ? $"(/{pattern}/)"
+            : $"(/{pattern}/ in {filePattern})";
+    }
+
+    private static string? FormatStringArg(FunctionCallContent call, string paramName)
+    {
+        string? value = GetString(call, paramName);
+        return value is not null ? $"({value})" : null;
+    }
+
+    private static string? FormatFallback(FunctionCallContent call)
+    {
+        if (call.Arguments is null || call.Arguments.Count == 0)
+        {
+            return null;
+        }
+
+        var parts = new List<string>();
+        foreach (var kvp in call.Arguments)
+        {
+            string? stringValue = kvp.Value switch
+            {
+                JsonElement je => je.ValueKind switch
+                {
+                    JsonValueKind.String => je.GetString(),
+                    JsonValueKind.Number => je.GetRawText(),
+                    JsonValueKind.True => "true",
+                    JsonValueKind.False => "false",
+                    _ => null,
+                },
+                not null => kvp.Value.ToString(),
+                _ => null,
+            };
+
+            if (stringValue is not null)
+            {
+                parts.Add($"{kvp.Key}: {Truncate(stringValue, 40)}");
+            }
+        }
+
+        return parts.Count > 0 ? $"({string.Join(", ", parts)})" : null;
+    }
+
+    private static string? GetString(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        return value switch
+        {
+            JsonElement je when je.ValueKind == JsonValueKind.String => je.GetString(),
+            string s => s,
+            _ => value.ToString(),
+        };
+    }
+
+    private static int? GetInt(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        return value switch
+        {
+            JsonElement je when je.ValueKind == JsonValueKind.Number => je.GetInt32(),
+            int i => i,
+            _ => int.TryParse(value.ToString(), out int parsed) ? parsed : null,
+        };
+    }
+
+    private static List<int>? GetIntList(FunctionCallContent call, string paramName)
+    {
+        if (call.Arguments?.TryGetValue(paramName, out object? value) != true || value is null)
+        {
+            return null;
+        }
+
+        var result = new List<int>();
+
+        if (value is JsonElement je && je.ValueKind == JsonValueKind.Array)
+        {
+            foreach (JsonElement item in je.EnumerateArray())
+            {
+                if (item.ValueKind == JsonValueKind.Number)
+                {
+                    result.Add(item.GetInt32());
+                }
+            }
+        }
+
+        return result.Count > 0 ? result : null;
+    }
+
+    private static string Truncate(string text, int maxLength)
+    {
+        return text.Length <= maxLength ? text : string.Concat(text.AsSpan(0, maxLength), "…");
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Observers/UsageDisplayObserver.cs

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using Microsoft.Extensions.AI;
+
+namespace Harness.Shared.Console.Observers;
+
+/// <summary>
+/// Displays token usage statistics (📊) from the response stream.
+/// </summary>
+internal sealed class UsageDisplayObserver : ConsoleObserver
+{
+    private readonly int? _maxContextWindowTokens;
+    private readonly int? _maxOutputTokens;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="UsageDisplayObserver"/> class.
+    /// </summary>
+    /// <param name="maxContextWindowTokens">Optional max context window size in tokens.</param>
+    /// <param name="maxOutputTokens">Optional max output tokens.</param>
+    public UsageDisplayObserver(int? maxContextWindowTokens, int? maxOutputTokens)
+    {
+        this._maxContextWindowTokens = maxContextWindowTokens;
+        this._maxOutputTokens = maxOutputTokens;
+    }
+
+    /// <inheritdoc/>
+    public override async Task OnContentAsync(ConsoleWriter writer, AIContent content)
+    {
+        if (content is UsageContent usage)
+        {
+            if (usage.Details is not null)
+            {
+                await writer.WriteInfoLineAsync(this.FormatUsageBreakdown(usage.Details), ConsoleColor.DarkGray);
+            }
+            else
+            {
+                await writer.WriteInfoLineAsync("📊 Tokens —", ConsoleColor.DarkGray);
+            }
+        }
+    }
+
+    private string FormatUsageBreakdown(UsageDetails details)
+    {
+        int? inputBudget = (this._maxContextWindowTokens is not null && this._maxOutputTokens is not null)
+            ? this._maxContextWindowTokens.Value - this._maxOutputTokens.Value
+            : null;
+
+        return $"📊 Tokens — input: {FormatTokenCount(details.InputTokenCount, inputBudget)}"
+            + $" | output: {FormatTokenCount(details.OutputTokenCount, this._maxOutputTokens)}"
+            + $" | total: {FormatTokenCount(details.TotalTokenCount, this._maxContextWindowTokens)}";
+    }
+
+    private static string FormatTokenCount(long? count, int? budget)
+    {
+        if (count is null)
+        {
+            return "—";
+        }
+
+        if (budget is not null && budget.Value > 0)
+        {
+            double pct = (double)count.Value / budget.Value * 100;
+            return $"{count.Value:N0}/{budget.Value:N0} ({pct:F1}%)";
+        }
+
+        return $"{count.Value:N0}";
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Shared_Console/Spinner.cs

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+namespace Harness.Shared.Console;
+
+/// <summary>
+/// A restartable spinner that can be started and stopped multiple times.
+/// </summary>
+internal sealed class Spinner : IDisposable
+{
+    private static readonly string[] s_frames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+
+    private CancellationTokenSource? _cts;
+    private Task? _task;
+
+    public void Start()
+    {
+        if (this._task is not null)
+        {
+            return;
+        }
+
+        this._cts = new CancellationTokenSource();
+        this._task = RunAsync(this._cts.Token);
+    }
+
+    public async Task StopAsync()
+    {
+        if (this._cts is null || this._task is null)
+        {
+            return;
+        }
+
+        this._cts.Cancel();
+        await this._task;
+        this._cts.Dispose();
+        this._cts = null;
+        this._task = null;
+    }
+
+    public void Dispose()
+    {
+        if (this._cts is not null && this._task is not null)
+        {
+            this._cts.Cancel();
+
+            // Block briefly to let the spinner task clean up.
+            // This prevents the background task from writing to the console after disposal.
+#pragma warning disable VSTHRD002 // Synchronous wait in Dispose is acceptable here — the spinner task completes quickly on cancellation.
+            this._task.Wait();
+#pragma warning restore VSTHRD002
+        }
+
+        this._cts?.Dispose();
+        this._cts = null;
+        this._task = null;
+    }
+
+    private static async Task RunAsync(CancellationToken cancellationToken)
+    {
+        int i = 0;
+        try
+        {
+            while (!cancellationToken.IsCancellationRequested)
+            {
+                System.Console.Write(s_frames[i % s_frames.Length]);
+                await Task.Delay(80, cancellationToken);
+                System.Console.Write("\b \b");
+                i++;
+            }
+        }
+        catch (OperationCanceledException)
+        {
+            // Clear the last spinner frame left on screen.
+            System.Console.Write("\b \b");
+        }
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Harness_Step01_Research.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Harness/Harness_Step01_Research/Program.cs

@@ -0,0 +1,190 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use a ChatClientAgent with the Harness AIContextProviders
+// (TodoProvider and AgentModeProvider) for interactive research tasks with web search
+// capabilities powered by Azure AI Foundry.
+// The agent plans research tasks, creates a todo list, gets user approval,
+// and then executes each step — all within an interactive conversation loop.
+//
+// Special commands:
+//   /todos  — Display the current todo list without invoking the agent.
+//   exit    — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Compaction;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+using SampleApp;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+
+// Create a ChatClientAgent with the Harness providers (TodoProvider and AgentModeProvider)
+// and research-focused instructions including the mandatory planning workflow.
+var instructions =
+    """
+    You are a research assistant. When given a research topic, research it thoroughly using web search and web browsing.
+    Use your knowledge to form good search queries and hypotheses, but always verify claims with the tools available to you rather than relying on memory alone.
+
+    ## Mandatory planning workflow
+
+    For every new substantive user request, including short factual questions, your behavior is determined by the mode you are in.
+    If you are in plan mode, start with the *Plan Mode* steps, and if you are in execute mode, skip directly to the *Execute Mode* steps below.
+
+    *Plan Mode*
+
+    1. Analyze the request with the purpose of building a research plan.
+    2. Create a list of todo items.
+    3. If needed, use the provided tools to do some exploratory checks to help build a plan and determine what clarifying questions you may need from the user.
+    4. Ask for clarifications from the user where needed.
+      1. Ask each clarification one by one.
+      2. When asking for clarification and you have specific options in mind, present them to the user, so they can choose the option instead of having to retype the entire response.
+      3. Do not proceed until you have received all the needed clarifications.
+      4. Do short exploratory research if it helps with being able to ask sensible clarifications from the user.
+    5. Write the plan to a memory file, so that it is retained even if compaction happens. Make sure to update the plan file if the user requests changes.
+    6. Present the plan to the user and ask for approval to switch to execute mode and process the plan.
+    7. When approval is granted, always switch to execute mode (using the `AgentMode_Set` tool), and follow the steps for *Execute mode*.
+
+    *Execute Mode*
+
+    1. If you don't have a plan or tasks yet, analyse the user request and create tasks and a plan. (**Skip this step if you came from plan mode**)
+    2. Work autonomously — use your best judgement to make decisions and keep progressing without asking the user questions. The goal is to have a complete, useful result ready when the user returns.
+    3. If you encounter ambiguity or an unexpected situation during execution, choose the most reasonable option, note your choice, and keep going.
+    4. Mark tasks as completed as you finish them.
+    5. Continue working, thinking and calling tools until you have the research result for the user.
+
+    ## General Instructions
+
+    - You must check the current mode after any user input, since the user may have changed the mode themselves,
+      e.g. the user may have switched to 'plan' mode after a previous research task finished in 'execute' mode, meaning they want to review a plan first before execution.
+    - Explain your reasoning and thought process as you work through tasks.
+    - Explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
+    - Avoid making more than 4 tool calls in a row without explaining what you are doing.
+    - Do not answer the underlying question before the plan has been presented and approved.
+    - This rule applies even when the answer seems obvious or the task seems small.
+    - For short requests, use a brief micro-plan rather than skipping planning. The only exceptions are:
+      - greetings,
+      - pure acknowledgments,
+      - clarification questions needed to form the plan,
+      - follow-up questions about results you have already presented,
+      - meta-discussion about the workflow itself.
+
+    **Todo management**
+
+    Mark each todo complete as you finish it so the list stays current.
+    If a todo turns out to be unnecessary or is blocked, remove it and briefly explain why.
+    Once the user finishes with a topic and moves onto a new one, clean up old completed todos by deleting them.
+
+    **Research quality**
+
+    Consult multiple sources when possible and cross-reference key claims.
+    When sources disagree, note the discrepancy and explain which source you consider more reliable and why.
+    If a web page fails to load or a search returns irrelevant results, try alternative search queries or sources before moving on.
+    Track your sources — you will need them when presenting results.
+
+    **Presenting results**
+
+    When presenting your final findings:
+    - Use clear sections with headings for each major topic or sub-question.
+    - Cite your sources inline (e.g., "According to [source name](URL), ...").
+    - End with a brief summary of key takeaways.
+    - Save the final research report to file memory so it survives compaction and can be referenced later.
+
+    **File memory**
+
+    Use the FileMemory_* tools to:
+    - Store downloaded search results or web pages.
+    - Store plans.
+    - Read the current plan to make sure tasks were done according to plan.
+    - Store findings.
+    - Check for relevant previously downloaded data / findings before starting new research.
+    """;
+
+// Create a compaction strategy based on the model's context window.
+// gpt-5.4: 1,050,000 token context window, 128,000 max output tokens.
+// Defaults: tool result eviction at 50% of input budget, truncation at 80%.
+var compactionStrategy = new ContextWindowCompactionStrategy(
+    maxContextWindowTokens: MaxContextWindowTokens,
+    maxOutputTokens: MaxOutputTokens);
+
+AIAgent agent =
+    // Create an OpenAIClient that communicates with the Foundry responses service.
+    new OpenAIClient(
+        // WARNING: DefaultAzureCredential is convenient for development but requires careful consideration in production.
+        // In production, consider using a specific credential (e.g., ManagedIdentityCredential) to avoid
+        // latency issues, unintended credential probing, and potential security risks from fallback mechanisms.
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)          // Enable retries to improve resiliency.
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)  // We want to manage chat history locally (not stored in the responses service), so that we can manage compaction ourselves.
+
+    // Build a ChatClient Pipeline
+    .AsBuilder()
+    .UseFunctionInvocation()                                // We are building our own stack from scratch so we need to include Function Invocation ourselves.
+    .UsePerServiceCallChatHistoryPersistence()              // Save chat history updates to the session after each service call, rather than only at the end of the run.
+    .UseAIContextProviders(new CompactionProvider(compactionStrategy))  // Add Compaction before each service call to responses so that long function invocation loops don't overflow the context.
+
+    // Build our agent on top of the ChatClient Pipeline
+    .BuildAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "ResearchAgent",
+            Description = "A research assistant that plans and executes research tasks.",
+            UseProvidedChatClientAsIs = true,                           // Since we built our own stack from scratch we need to tell the agent not to also add defaults like Function Invocation.
+            RequirePerServiceCallChatHistoryPersistence = true,         // Since we are added the per service call persistence ChatClient, we need to tell the agent to not also store chat history at the end of the run.
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(      // Store chat history in memory in the session object. Will persist if the session is persisted.
+                new InMemoryChatHistoryProviderOptions
+                {
+                    ChatReducer = compactionStrategy.AsChatReducer(),   // Run compaction on the InMemory chat history when it gets too large.
+                }),
+            AIContextProviders =
+            [
+                new TodoProvider(),         // Add an AIContextProvider to allow the agent to create a TODO list, which is stored in the session.
+                new AgentModeProvider(),    // Add an AIContextProvider that tracks the agent mode and allows switching mode. Current mode is stored in the session.
+                new FileMemoryProvider(     // Add an AIContextProvider that can store memories in files under a session specific working folder.
+                    new FileSystemAgentFileStore(Path.Combine(AppContext.BaseDirectory, "agent-files")),
+                    (_) => new FileMemoryState() { WorkingFolder = DateTime.UtcNow.ToString("yyyyMMdd_HHmmss") + "_" + Guid.NewGuid().ToString() })
+            ],
+            ChatOptions = new ChatOptions
+            {
+                Instructions = instructions,
+                Tools =
+                [
+                    ResponseTool.CreateWebSearchTool().AsAITool(),          // Add the foundry hosted web search tool that runs in the service.
+                    new WebBrowsingTool(),                                  // Add a local web browsing tool that converts html to markdown.
+                ],
+                MaxOutputTokens = MaxOutputTokens,                          // Set a high token limit for long research tasks with many tool calls and long outputs.
+                Reasoning = new() { Effort = ReasoningEffort.Medium },
+            },
+        })
+    .AsBuilder()
+    .UseToolApproval()                                                      // Add the ability to auto approve tools once a user has said they don't want to be asked again. Approval rules are tied to the session.
+    .Build();
+
+// Run the interactive console session using the shared HarnessConsole helper.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    title: "Research Assistant",
+    userPrompt: "Enter a research topic to get started.",
+    new HarnessConsoleOptions
+    {
+        MaxContextWindowTokens = MaxContextWindowTokens,
+        MaxOutputTokens = MaxOutputTokens,
+        EnablePlanningUx = true,
+        PlanningModeName = "plan",
+        ExecutionModeName = "execute"
+    });

dotnet/samples/02-agents/Harness/Harness_Step01_Research/README.md

@@ -0,0 +1,52 @@
+# What this sample demonstrates
+
+This sample demonstrates how to use a `ChatClientAgent` with the Harness `AIContextProviders` (`TodoProvider` and `AgentModeProvider`) for interactive research tasks with web search capabilities powered by Azure AI Foundry.
+
+Key features showcased:
+
+- **ChatClientAgent** — configured directly with Harness providers for planning and task management
+- **Web Search** — the agent can search the web for current information via `ResponseTool.CreateWebSearchTool()`
+- **TodoProvider** — the agent creates and manages a todo list to track research questions
+- **AgentModeProvider** — the agent switches between "plan" mode (breaking down the topic) and "execute" mode (answering each research question)
+- **Interactive conversation** — you can review the agent's plan, provide feedback, and approve before execution begins
+- **Streaming output** — responses are streamed token-by-token for a natural experience
+- **`/todos` command** — view the current todo list at any time without invoking the agent
+- **Mode-based coloring** — console output is colored based on the agent's current mode (cyan for plan, green for execute)
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. An Azure AI Foundry project with a deployed model (e.g., `gpt-5.4`)
+2. Azure CLI installed and authenticated (`az login`)
+
+## Environment Variables
+
+Set the following environment variables:
+
+```bash
+# Required: Your Azure AI Foundry OpenAI endpoint
+export AZURE_FOUNDRY_OPENAI_ENDPOINT="https://your-project.services.ai.azure.com/openai/v1/"
+
+# Optional: Model deployment name (defaults to gpt-5.4)
+export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4"
+```
+
+## Running the Sample
+
+```bash
+cd dotnet
+dotnet run --project samples/02-agents/Harness/Harness_Step01_Research
+```
+
+## What to Expect
+
+The sample starts an interactive conversation loop. You can:
+
+1. **Enter a research topic** — the agent will analyze it and create a plan with todos
+2. **Review and adjust** — provide feedback on the plan, ask for changes, or approve it
+3. **Type `/todos`** — to see the current todo list at any time
+4. **Watch execution** — once approved, tell the agent to proceed and it will work through each todo
+5. **Type `exit`** — to end the session
+
+The prompt and agent output are colored by the current mode: **cyan** during planning, **green** during execution.

dotnet/samples/02-agents/Harness/Harness_Step01_Research/WebBrowsingTool.cs

@@ -0,0 +1,287 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.ComponentModel;
+using System.Net;
+using System.Text.Json;
+using System.Text.RegularExpressions;
+using Microsoft.Extensions.AI;
+
+namespace SampleApp;
+
+/// <summary>
+/// An AI function that downloads HTML pages and converts them to markdown.
+/// </summary>
+internal sealed partial class WebBrowsingTool : AIFunction
+{
+    private static readonly HttpClient s_httpClient = new();
+    private readonly AIFunction _inner = AIFunctionFactory.Create(DownloadUriAsync);
+
+    /// <inheritdoc/>
+    public override string Name => this._inner.Name;
+
+    /// <inheritdoc/>
+    public override string Description => this._inner.Description;
+
+    /// <inheritdoc/>
+    public override JsonElement JsonSchema => this._inner.JsonSchema;
+
+    /// <inheritdoc/>
+    protected override ValueTask<object?> InvokeCoreAsync(
+        AIFunctionArguments arguments,
+        CancellationToken cancellationToken) =>
+        this._inner.InvokeAsync(arguments, cancellationToken);
+
+    [Description("Fetch the html from the given url as markdown")]
+    private static async Task<string> DownloadUriAsync(
+        [Description("The URL to download")] string uri,
+        CancellationToken cancellationToken = default)
+    {
+        if (!Uri.TryCreate(uri, UriKind.Absolute, out Uri? parsedUri))
+        {
+            return $"Error: '{uri}' is not a valid URL.";
+        }
+
+        if (parsedUri.Scheme is not "http" and not "https")
+        {
+            return $"Error: Only HTTP and HTTPS URLs are supported. Got: '{parsedUri.Scheme}'.";
+        }
+
+        // NOTE: In production scenarios, consider also blocking requests to private/internal IP
+        // ranges (e.g., 10.x.x.x, 172.16-31.x.x, 192.168.x.x, 127.0.0.1, 169.254.169.254)
+        // to prevent SSRF attacks via prompt injection in web content.
+
+        try
+        {
+            string html = await s_httpClient.GetStringAsync(parsedUri, cancellationToken);
+            return HtmlToMarkdownConverter.Convert(html);
+        }
+        catch (HttpRequestException ex)
+        {
+            return $"Error downloading {uri}: {ex.Message}";
+        }
+    }
+
+    /// <summary>
+    /// A simple HTML to Markdown converter using regex-based transformations.
+    /// Handles the most common HTML elements without requiring external dependencies.
+    /// </summary>
+    private static partial class HtmlToMarkdownConverter
+    {
+        public static string Convert(string html)
+        {
+            // Extract body content if present, otherwise use the full HTML.
+            var bodyMatch = BodyRegex().Match(html);
+            string content = bodyMatch.Success ? bodyMatch.Groups[1].Value : html;
+
+            // Remove script, style, and head blocks.
+            content = ScriptRegex().Replace(content, string.Empty);
+            content = StyleRegex().Replace(content, string.Empty);
+            content = HeadRegex().Replace(content, string.Empty);
+            content = CommentRegex().Replace(content, string.Empty);
+
+            // Convert block elements before inline elements.
+            content = ConvertHeadings(content);
+            content = ConvertCodeBlocks(content);
+            content = ConvertBlockquotes(content);
+            content = ConvertLists(content);
+            content = ConvertHorizontalRules(content);
+
+            // Convert inline elements.
+            content = ConvertLinks(content);
+            content = ConvertImages(content);
+            content = ConvertBold(content);
+            content = ConvertItalic(content);
+            content = ConvertInlineCode(content);
+
+            // Convert structural elements.
+            content = ConvertParagraphs(content);
+            content = ConvertLineBreaks(content);
+
+            // Strip remaining HTML tags.
+            content = StripTagsRegex().Replace(content, string.Empty);
+
+            // Decode HTML entities.
+            content = WebUtility.HtmlDecode(content);
+
+            // Clean up excessive whitespace.
+            content = ExcessiveNewlinesRegex().Replace(content, "\n\n");
+
+            return content.Trim();
+        }
+
+        private static string ConvertHeadings(string html)
+        {
+            html = H1Regex().Replace(html, m => $"\n# {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H2Regex().Replace(html, m => $"\n## {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H3Regex().Replace(html, m => $"\n### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H4Regex().Replace(html, m => $"\n#### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H5Regex().Replace(html, m => $"\n##### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            html = H6Regex().Replace(html, m => $"\n###### {StripInnerTags(m.Groups[1].Value).Trim()}\n");
+            return html;
+        }
+
+        private static string ConvertLinks(string html) =>
+            LinkRegex().Replace(html, m =>
+            {
+                string href = m.Groups[1].Value;
+                string text = StripInnerTags(m.Groups[2].Value).Trim();
+
+                // Skip javascript and data links.
+                if (href.StartsWith("javascript:", StringComparison.OrdinalIgnoreCase) ||
+                    href.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+                {
+                    return text;
+                }
+
+                return string.IsNullOrWhiteSpace(text) ? string.Empty : $"[{text}]({href})";
+            });
+
+        private static string ConvertImages(string html) =>
+            ImageRegex().Replace(html, m =>
+            {
+                string src = m.Groups[1].Value;
+                string alt = m.Groups[2].Value;
+
+                // Truncate data URIs.
+                if (src.StartsWith("data:", StringComparison.OrdinalIgnoreCase))
+                {
+                    src = src.Split(',')[0] + "...";
+                }
+
+                return $"![{alt}]({src})";
+            });
+
+        private static string ConvertBold(string html) =>
+            BoldRegex().Replace(html, m => $"**{m.Groups[2].Value}**");
+
+        private static string ConvertItalic(string html) =>
+            ItalicRegex().Replace(html, m => $"*{m.Groups[2].Value}*");
+
+        private static string ConvertInlineCode(string html) =>
+            InlineCodeRegex().Replace(html, m => $"`{m.Groups[1].Value}`");
+
+        private static string ConvertCodeBlocks(string html) =>
+            CodeBlockRegex().Replace(html, m => $"\n```\n{StripInnerTags(m.Groups[1].Value).Trim()}\n```\n");
+
+        private static string ConvertBlockquotes(string html) =>
+            BlockquoteRegex().Replace(html, m =>
+            {
+                string inner = StripInnerTags(m.Groups[1].Value).Trim();
+                // Prefix each line with "> ".
+                string quoted = string.Join("\n", inner.Split('\n').Select(line => $"> {line.Trim()}"));
+                return $"\n{quoted}\n";
+            });
+
+        private static string ConvertLists(string html)
+        {
+            // Unordered lists.
+            html = UlRegex().Replace(html, m =>
+            {
+                string items = LiRegex().Replace(m.Groups[1].Value, li => $"- {StripInnerTags(li.Groups[1].Value).Trim()}\n");
+                return $"\n{items}";
+            });
+
+            // Ordered lists.
+            html = OlRegex().Replace(html, m =>
+            {
+                int index = 1;
+                string items = LiRegex().Replace(m.Groups[1].Value, li => $"{index++}. {StripInnerTags(li.Groups[1].Value).Trim()}\n");
+                return $"\n{items}";
+            });
+
+            return html;
+        }
+
+        private static string ConvertHorizontalRules(string html) =>
+            HrRegex().Replace(html, "\n---\n");
+
+        private static string ConvertParagraphs(string html) =>
+            ParagraphRegex().Replace(html, m => $"\n\n{m.Groups[1].Value}\n\n");
+
+        private static string ConvertLineBreaks(string html) =>
+            BrRegex().Replace(html, "\n");
+
+        private static string StripInnerTags(string html) =>
+            StripTagsRegex().Replace(html, string.Empty);
+
+        // Source-generated regex patterns for performance and AOT compatibility.
+
+        [GeneratedRegex(@"<body[^>]*>(.*?)</body>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex BodyRegex();
+
+        [GeneratedRegex(@"<script[^>]*>.*?</script>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ScriptRegex();
+
+        [GeneratedRegex(@"<style[^>]*>.*?</style>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex StyleRegex();
+
+        [GeneratedRegex(@"<head[^>]*>.*?</head>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex HeadRegex();
+
+        [GeneratedRegex(@"<!--.*?-->", RegexOptions.Singleline)]
+        private static partial Regex CommentRegex();
+
+        [GeneratedRegex(@"<h1[^>]*>(.*?)</h1>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H1Regex();
+
+        [GeneratedRegex(@"<h2[^>]*>(.*?)</h2>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H2Regex();
+
+        [GeneratedRegex(@"<h3[^>]*>(.*?)</h3>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H3Regex();
+
+        [GeneratedRegex(@"<h4[^>]*>(.*?)</h4>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H4Regex();
+
+        [GeneratedRegex(@"<h5[^>]*>(.*?)</h5>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H5Regex();
+
+        [GeneratedRegex(@"<h6[^>]*>(.*?)</h6>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex H6Regex();
+
+        [GeneratedRegex(@"<a\s[^>]*href=[""']([^""']*)[""'][^>]*>(.*?)</a>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex LinkRegex();
+
+        [GeneratedRegex(@"<img\s[^>]*src=[""']([^""']*)[""'][^>]*?(?:alt=[""']([^""']*)[""'])?[^>]*/?>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ImageRegex();
+
+        [GeneratedRegex(@"<(strong|b)\b[^>]*>(.*?)</\1>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex BoldRegex();
+
+        [GeneratedRegex(@"<(em|i)\b[^>]*>(.*?)</\1>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ItalicRegex();
+
+        [GeneratedRegex(@"<code[^>]*>(.*?)</code>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex InlineCodeRegex();
+
+        [GeneratedRegex(@"<pre[^>]*>(.*?)</pre>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex CodeBlockRegex();
+
+        [GeneratedRegex(@"<blockquote[^>]*>(.*?)</blockquote>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex BlockquoteRegex();
+
+        [GeneratedRegex(@"<ul[^>]*>(.*?)</ul>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex UlRegex();
+
+        [GeneratedRegex(@"<ol[^>]*>(.*?)</ol>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex OlRegex();
+
+        [GeneratedRegex(@"<li[^>]*>(.*?)</li>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex LiRegex();
+
+        [GeneratedRegex(@"<hr\s*/?>", RegexOptions.IgnoreCase)]
+        private static partial Regex HrRegex();
+
+        [GeneratedRegex(@"<p[^>]*>(.*?)</p>", RegexOptions.Singleline | RegexOptions.IgnoreCase)]
+        private static partial Regex ParagraphRegex();
+
+        [GeneratedRegex(@"<br\s*/?>", RegexOptions.IgnoreCase)]
+        private static partial Regex BrRegex();
+
+        [GeneratedRegex(@"<[^>]+>")]
+        private static partial Regex StripTagsRegex();
+
+        [GeneratedRegex(@"\n{3,}")]
+        private static partial Regex ExcessiveNewlinesRegex();
+    }
+}

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Harness_Step02_Research_WithSubAgents.csproj

@@ -0,0 +1,20 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/Program.cs

@@ -0,0 +1,106 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use the SubAgentsProvider to delegate work to sub-agents.
+// A parent agent is given a list of stock tickers and instructed to find the closing price
+// for each ticker on December 31, 2025. It delegates the web searches to a sub-agent
+// equipped with Foundry's hosted web search tool.
+//
+// Special commands:
+//   exit    — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
+
+// --- Sub-agent: Web Search Agent ---
+// This agent can search the web and is used by the parent agent to look up stock prices.
+AIAgent webSearchAgent =
+    new OpenAIClient(
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+    .AsAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "WebSearchAgent",
+            Description = "An agent that can search the web to find information.",
+            ChatOptions = new ChatOptions
+            {
+                Instructions = "You are a web search assistant. When asked to find information, use the web search tool to look it up and return a concise, factual answer.",
+                Tools =
+                [
+                    ResponseTool.CreateWebSearchTool().AsAITool(),
+                ],
+            },
+        });
+
+// --- Parent agent: Stock Price Researcher ---
+// This agent orchestrates the sub-agent to look up stock prices in parallel.
+var parentInstructions =
+    """
+    You are a stock price research assistant. You have access to a web search sub-agent that can look up information on the web.
+
+    When given a list of stock tickers, your job is to find the closing price for each ticker on December 31, 2025.
+
+    ## Workflow
+
+    1. For each ticker, start a sub-task on the WebSearchAgent asking it to find the closing price on December 31, 2025.
+       - Start all sub-tasks before waiting for any of them to complete, so they run concurrently.
+    2. Wait for all sub-tasks to complete.
+    3. Retrieve the results from each sub-task.
+    4. Present a summary table with the ticker symbol and closing price for each stock.
+    5. Clear all completed tasks to free memory.
+
+    ## Important
+
+    - Always delegate web searches to the WebSearchAgent sub-agent. Do not try to answer from memory.
+    - If a sub-task fails or returns unclear results, continue the task with a more specific query.
+    - Present results in a clean markdown table format.
+    """;
+
+AIAgent parentAgent =
+    new OpenAIClient(
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+    .AsAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "StockPriceResearcher",
+            Description = "An agent that researches stock prices using sub-agents.",
+            AIContextProviders =
+            [
+                new SubAgentsProvider([webSearchAgent]),
+            ],
+            ChatOptions = new ChatOptions
+            {
+                Instructions = parentInstructions,
+                MaxOutputTokens = 16_000,
+            },
+        });
+
+// Run the interactive console session.
+await HarnessConsole.RunAgentAsync(
+    parentAgent,
+    title: "Stock Price Researcher (SubAgents Demo)",
+    userPrompt: "Enter a list of stock tickers (e.g., BAC, MSFT, BA):");

dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents/README.md

@@ -0,0 +1,53 @@
+# Harness Step 02 — SubAgents (Stock Price Research)
+
+This sample demonstrates how to use the **SubAgentsProvider** to delegate work from a parent agent to sub-agents.
+
+## What It Does
+
+A parent agent receives a list of stock tickers and uses a web-search sub-agent to find the closing price for each ticker on December 31, 2025. The sub-tasks run concurrently, and results are presented in a summary table.
+
+### Architecture
+
+```
+┌─────────────────────────────────┐
+│     StockPriceResearcher        │
+│         (Parent Agent)          │
+│                                 │
+│  SubAgentsProvider              │
+│    ├─ SubAgents_StartTask       │
+│    ├─ SubAgents_WaitFor...      │
+│    ├─ SubAgents_GetTaskResults  │
+│    └─ ...                       │
+└────────────┬────────────────────┘
+             │  delegates to
+             ▼
+┌─────────────────────────────────┐
+│       WebSearchAgent            │
+│        (Sub-Agent)              │
+│                                 │
+│  Tools:                         │
+│    └─ web_search (Foundry)      │
+└─────────────────────────────────┘
+```
+
+## Prerequisites
+
+- An Azure AI Foundry endpoint with an OpenAI model deployment
+- Set the following environment variables:
+  - `AZURE_FOUNDRY_OPENAI_ENDPOINT` — Your Foundry OpenAI endpoint URL
+  - `AZURE_AI_MODEL_DEPLOYMENT_NAME` — Model deployment name (defaults to `gpt-5.4`)
+
+## Running the Sample
+
+```bash
+cd dotnet/samples/02-agents/Harness/Harness_Step02_Research_WithSubAgents
+dotnet run
+```
+
+When prompted, enter a list of stock tickers such as:
+
+```
+BAC, MSFT, BA
+```
+
+The parent agent will delegate each ticker lookup to the web search sub-agent concurrently and present the results in a table.

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Harness_Step03_DataProcessing.csproj

@@ -0,0 +1,24 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFrameworks>net10.0</TargetFrameworks>
+
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Azure.Identity" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <ProjectReference Include="..\..\..\..\src\Microsoft.Agents.AI.OpenAI\Microsoft.Agents.AI.OpenAI.csproj" />
+    <ProjectReference Include="..\Harness_Shared_Console\Harness_Shared_Console.csproj" />
+  </ItemGroup>
+
+  <ItemGroup>
+    <Content Include="data\**\*" CopyToOutputDirectory="PreserveNewest" />
+  </ItemGroup>
+
+</Project>

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/Program.cs

@@ -0,0 +1,110 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+// This sample demonstrates how to use a ChatClientAgent with the FileAccessProvider
+// to give an agent access to a folder of CSV data files. The agent can read, analyze,
+// and extract information from the data, then write results back as new files.
+//
+// The sample includes a pre-populated `data/` folder with sales transaction data.
+// Ask the agent to analyze the data, produce summaries, or create new output files.
+//
+// Special commands:
+//   exit — End the session.
+
+#pragma warning disable OPENAI001 // Suppress experimental API warnings for Responses API usage.
+#pragma warning disable MAAI001  // Suppress experimental API warnings for Agents AI experiments.
+
+using System.ClientModel.Primitives;
+using Azure.Identity;
+using Harness.Shared.Console;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.Compaction;
+using Microsoft.Extensions.AI;
+using OpenAI;
+using OpenAI.Responses;
+
+var endpoint = Environment.GetEnvironmentVariable("AZURE_FOUNDRY_OPENAI_ENDPOINT") ?? throw new InvalidOperationException("AZURE_FOUNDRY_OPENAI_ENDPOINT is not set.");
+var deploymentName = Environment.GetEnvironmentVariable("AZURE_AI_MODEL_DEPLOYMENT_NAME") ?? "gpt-5.4";
+
+const int MaxContextWindowTokens = 1_050_000;
+const int MaxOutputTokens = 128_000;
+
+// Point the file store at the data/ folder that ships with the sample.
+var dataFolder = Path.Combine(AppContext.BaseDirectory, "data");
+var fileStore = new FileSystemAgentFileStore(dataFolder);
+
+var instructions =
+    """
+    You are a data analyst assistant. You have access to a folder of data files via the FileAccess_* tools.
+
+    ## Getting started
+    - Start by listing available files with FileAccess_ListFiles to see what data is available.
+    - Read the files to understand their structure and contents.
+
+    ## Working with data
+    - When asked to analyze data, read the relevant files first, then perform the analysis.
+    - Show your analysis clearly with tables, summaries, and key insights.
+    - When calculations are needed, work through them step by step and show your reasoning.
+
+    ## Writing output
+    - When asked to produce output files (e.g., reports, summaries, filtered data), use FileAccess_SaveFile to write them.
+    - Use appropriate file formats: CSV for tabular data, Markdown for reports.
+    - Confirm what you wrote and where.
+
+    ## Important
+    - Never modify or delete the original input data files unless explicitly asked to do so.
+    - If asked about data you haven't read yet, read it first before answering.
+    - Always explain your reasoning and thought process as you work through tasks.
+    - Always explain what you learned and what you are going to do next between tool calls, so the user can follow along with your thought process.
+    """;
+
+// Create a compaction strategy based on the model's context window.
+var compactionStrategy = new ContextWindowCompactionStrategy(
+    maxContextWindowTokens: MaxContextWindowTokens,
+    maxOutputTokens: MaxOutputTokens);
+
+AIAgent agent =
+    new OpenAIClient(
+        new BearerTokenPolicy(new DefaultAzureCredential(), "https://ai.azure.com/.default"),
+        new OpenAIClientOptions()
+        {
+            Endpoint = new Uri(endpoint),
+            RetryPolicy = new ClientRetryPolicy(3)
+        })
+    .GetResponsesClient()
+    .AsIChatClientWithStoredOutputDisabled(deploymentName)
+
+    .AsBuilder()
+    .UseFunctionInvocation()
+    .UsePerServiceCallChatHistoryPersistence()
+    .UseAIContextProviders(new CompactionProvider(compactionStrategy))
+
+    .BuildAIAgent(
+        new ChatClientAgentOptions
+        {
+            Name = "DataAnalyst",
+            Description = "A data analyst assistant that reads, analyzes, and processes data files.",
+            UseProvidedChatClientAsIs = true,
+            RequirePerServiceCallChatHistoryPersistence = true,
+            ChatHistoryProvider = new InMemoryChatHistoryProvider(
+                new InMemoryChatHistoryProviderOptions
+                {
+                    ChatReducer = compactionStrategy.AsChatReducer(),
+                }),
+            AIContextProviders =
+            [
+                new FileAccessProvider(fileStore),
+            ],
+            ChatOptions = new ChatOptions
+            {
+                Instructions = instructions,
+                MaxOutputTokens = MaxOutputTokens,
+            },
+        })
+    .AsBuilder()
+    .Build();
+
+// Run the interactive console session.
+await HarnessConsole.RunAgentAsync(
+    agent,
+    title: "Data Processing Assistant",
+    userPrompt: "Ask me to analyze the data files, produce summaries, or create output files.");

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/README.md

@@ -0,0 +1,65 @@
+# What this sample demonstrates
+
+This sample demonstrates how to use a `ChatClientAgent` with the `FileAccessProvider` to give an agent access to a folder of data files for reading, analyzing, and writing results.
+
+Key features showcased:
+
+- **FileAccessProvider** — gives the agent tools to read, write, list, search, and delete files in a shared data folder
+- **CSV data processing** — the agent reads sales transaction data and performs analysis on demand
+- **Output file creation** — the agent can write summaries, filtered data, or reports back to the data folder
+- **Streaming output** — responses are streamed token-by-token for a natural experience
+- **No planning mode** — this is a simple conversational sample focused on data interaction
+
+## Prerequisites
+
+Before running this sample, ensure you have:
+
+1. An Azure AI Foundry project with a deployed model (e.g., `gpt-5.4`)
+2. Azure CLI installed and authenticated (`az login`)
+
+## Environment Variables
+
+Set the following environment variables:
+
+```bash
+# Required: Your Azure AI Foundry OpenAI endpoint
+export AZURE_FOUNDRY_OPENAI_ENDPOINT="https://your-project.services.ai.azure.com/openai/v1/"
+
+# Optional: Model deployment name (defaults to gpt-5.4)
+export AZURE_AI_MODEL_DEPLOYMENT_NAME="gpt-5.4"
+```
+
+## Running the Sample
+
+```bash
+cd dotnet
+dotnet run --project samples/02-agents/Harness/Harness_Step03_DataProcessing
+```
+
+## What to Expect
+
+The sample starts an interactive conversation with a data analyst agent. The `data/` folder contains a `sales.csv` file with ~50 rows of sales transaction data (date, product, category, quantity, unit price, region, salesperson).
+
+You can ask the agent to:
+
+1. **List available files** — "What files do you have?"
+2. **Analyze the data** — "What are the total sales by region?" or "Which salesperson has the highest revenue?"
+3. **Create output files** — "Create a summary report as a markdown file" or "Write a CSV with monthly totals"
+4. **Search for patterns** — "Find all transactions over $1000"
+5. **Type `exit`** — to end the session
+
+E.g. try the following prompt `Please process the sales.csv file by first filtering it to only North region sales, and then calculating the sum of sales by person. I'd like to write the results of the processing to north_region_totals.csv`.
+
+## Sample Data
+
+The included `data/sales.csv` contains sales transactions from January to March 2025 with the following columns:
+
+| Column | Description |
+| --- | --- |
+| `date` | Transaction date (YYYY-MM-DD) |
+| `product` | Product name |
+| `category` | Product category (Electronics, Furniture, Stationery) |
+| `quantity` | Units sold |
+| `unit_price` | Price per unit |
+| `region` | Sales region (North, South, West) |
+| `salesperson` | Name of the salesperson |

dotnet/samples/02-agents/Harness/Harness_Step03_DataProcessing/data/sales.csv

@@ -0,0 +1,50 @@
+date,product,category,quantity,unit_price,region,salesperson
+2025-01-03,Laptop Pro 15,Electronics,2,1299.99,North,Alice
+2025-01-05,Ergonomic Chair,Furniture,5,349.50,South,Bob
+2025-01-07,Wireless Mouse,Electronics,12,24.99,North,Alice
+2025-01-08,Standing Desk,Furniture,1,599.00,West,Carol
+2025-01-10,USB-C Hub,Electronics,8,45.99,North,David
+2025-01-12,Monitor 27in,Electronics,3,429.00,South,Bob
+2025-01-14,Desk Lamp,Furniture,6,79.95,West,Carol
+2025-01-15,Keyboard Mech,Electronics,4,149.99,North,Alice
+2025-01-17,Filing Cabinet,Furniture,2,189.00,South,David
+2025-01-20,Webcam HD,Electronics,10,89.99,West,Bob
+2025-01-22,Laptop Pro 15,Electronics,1,1299.99,South,Carol
+2025-01-24,Ergonomic Chair,Furniture,3,349.50,North,Alice
+2025-01-25,Notebook Pack,Stationery,20,12.99,South,David
+2025-01-27,Wireless Mouse,Electronics,15,24.99,West,Carol
+2025-01-28,Whiteboard,Stationery,4,129.00,North,Bob
+2025-01-30,Standing Desk,Furniture,2,599.00,South,Alice
+2025-02-02,USB-C Hub,Electronics,6,45.99,West,David
+2025-02-04,Monitor 27in,Electronics,2,429.00,North,Carol
+2025-02-05,Desk Lamp,Furniture,8,79.95,South,Bob
+2025-02-07,Keyboard Mech,Electronics,5,149.99,West,Alice
+2025-02-09,Filing Cabinet,Furniture,1,189.00,North,David
+2025-02-11,Webcam HD,Electronics,7,89.99,South,Carol
+2025-02-13,Laptop Pro 15,Electronics,3,1299.99,West,Bob
+2025-02-15,Notebook Pack,Stationery,30,12.99,North,Alice
+2025-02-17,Ergonomic Chair,Furniture,4,349.50,South,David
+2025-02-19,Wireless Mouse,Electronics,20,24.99,North,Carol
+2025-02-20,Whiteboard,Stationery,2,129.00,West,Bob
+2025-02-22,Standing Desk,Furniture,1,599.00,North,Alice
+2025-02-24,USB-C Hub,Electronics,10,45.99,South,David
+2025-02-26,Monitor 27in,Electronics,4,429.00,West,Carol
+2025-02-28,Desk Lamp,Furniture,3,79.95,North,Bob
+2025-03-02,Keyboard Mech,Electronics,6,149.99,South,Alice
+2025-03-04,Filing Cabinet,Furniture,3,189.00,West,David
+2025-03-06,Webcam HD,Electronics,9,89.99,North,Carol
+2025-03-08,Laptop Pro 15,Electronics,2,1299.99,South,Bob
+2025-03-10,Notebook Pack,Stationery,25,12.99,West,Alice
+2025-03-12,Ergonomic Chair,Furniture,6,349.50,North,David
+2025-03-14,Wireless Mouse,Electronics,18,24.99,South,Carol
+2025-03-15,Whiteboard,Stationery,5,129.00,North,Bob
+2025-03-17,Standing Desk,Furniture,3,599.00,West,Alice
+2025-03-19,USB-C Hub,Electronics,7,45.99,North,David
+2025-03-21,Monitor 27in,Electronics,5,429.00,South,Carol
+2025-03-23,Desk Lamp,Furniture,4,79.95,West,Bob
+2025-03-25,Keyboard Mech,Electronics,3,149.99,North,Alice
+2025-03-27,Filing Cabinet,Furniture,2,189.00,South,David
+2025-03-28,Webcam HD,Electronics,11,89.99,West,Carol
+2025-03-29,Laptop Pro 15,Electronics,1,1299.99,North,Bob
+2025-03-30,Notebook Pack,Stationery,15,12.99,South,Alice
+2025-03-31,Ergonomic Chair,Furniture,2,349.50,West,David

dotnet/samples/02-agents/Harness/README.md

@@ -0,0 +1,11 @@
+# Harness Agent Samples
+
+Samples demonstrating the [Harness AIContextProviders](../../../src/Microsoft.Agents.AI/Harness/) — reusable providers that add planning, task management, and mode tracking to any `ChatClientAgent`.
+
+## Samples
+
+| Sample | Description |
+| --- | --- |
+| [Harness_Step01_Research](./Harness_Step01_Research/README.md) | Using a ChatClientAgent with TodoProvider and AgentModeProvider for research, showcasing planning mode and todo management |
+| [Harness_Step02_Research_WithSubAgents](./Harness_Step02_Research_WithSubAgents/README.md) | Using SubAgentsProvider to delegate stock price lookups to a web-search sub-agent concurrently |
+| [Harness_Step03_DataProcessing](./Harness_Step03_DataProcessing/README.md) | Using FileAccessProvider to give an agent access to CSV data files for reading, analysis, and output generation |

dotnet/samples/02-agents/README.md

@@ -16,6 +16,7 @@ The getting started samples demonstrate the fundamental concepts and functionali
 | [Agent With Anthropic](./AgentWithAnthropic/README.md) | Getting started with agents using Anthropic Claude |
 | [Model Context Protocol](./ModelContextProtocol/README.md) | Getting started with Model Context Protocol |
 | [Agent Skills](./AgentSkills/README.md) | Getting started with Agent Skills |
+| [Agent Harness with built-in tools](./Harness/README.md) | Demonstrating how to build an Agent Harness with built-in planning, todo, and mode management tooling |
 | [Declarative Agents](./DeclarativeAgents) | Loading and executing AI agents from YAML configuration files |
 | [AG-UI](./AGUI/README.md) | Getting started with AG-UI (Agent UI Protocol) servers and clients |
 | [Dev UI](./DevUI/README.md) | Interactive web interface for testing and debugging AI agents during development |

dotnet/src/Microsoft.Agents.AI/AgentJsonUtilities.cs

@@ -1,5 +1,6 @@
 // Copyright (c) Microsoft. All rights reserved.
 
+using System.Collections.Generic;
 using System.Diagnostics.CodeAnalysis;
 using System.Text.Encodings.Web;
 using System.Text.Json;
@@ -69,6 +70,38 @@ internal static partial class AgentJsonUtilities
     [JsonSerializable(typeof(TextSearchProvider.TextSearchProviderState))]
     [JsonSerializable(typeof(ChatHistoryMemoryProvider.State))]
 
+    // TodoProvider types
+    [JsonSerializable(typeof(TodoState))]
+    [JsonSerializable(typeof(TodoItem))]
+    [JsonSerializable(typeof(TodoItemInput))]
+    [JsonSerializable(typeof(List<int>), TypeInfoPropertyName = "IntList")]
+    [JsonSerializable(typeof(List<TodoItem>), TypeInfoPropertyName = "TodoItemList")]
+    [JsonSerializable(typeof(List<TodoItemInput>), TypeInfoPropertyName = "TodoItemInputList")]
+
+    // AgentModeProvider types
+    [JsonSerializable(typeof(AgentModeState))]
+
+    // ToolApprovalAgent types
+    [JsonSerializable(typeof(ToolApprovalState))]
+    [JsonSerializable(typeof(ToolApprovalRule))]
+    [JsonSerializable(typeof(List<ToolApprovalRule>), TypeInfoPropertyName = "ToolApprovalRuleList")]
+
+    // FileMemoryProvider types
+    [JsonSerializable(typeof(FileMemoryState))]
+    [JsonSerializable(typeof(FileSearchResult))]
+    [JsonSerializable(typeof(List<FileSearchResult>), TypeInfoPropertyName = "FileSearchResultList")]
+    [JsonSerializable(typeof(FileSearchMatch))]
+    [JsonSerializable(typeof(List<FileSearchMatch>), TypeInfoPropertyName = "FileSearchMatchList")]
+    [JsonSerializable(typeof(FileListEntry))]
+    [JsonSerializable(typeof(List<FileListEntry>), TypeInfoPropertyName = "FileListEntryList")]
+
+    // SubAgentsProvider types
+    [JsonSerializable(typeof(SubAgentState))]
+    [JsonSerializable(typeof(SubAgentRuntimeState))]
+    [JsonSerializable(typeof(SubTaskInfo))]
+    [JsonSerializable(typeof(SubTaskStatus))]
+    [JsonSerializable(typeof(List<SubTaskInfo>), TypeInfoPropertyName = "SubTaskInfoList")]
+
     [ExcludeFromCodeCoverage]
     internal sealed partial class JsonContext : JsonSerializerContext;
 }

dotnet/src/Microsoft.Agents.AI/ChatClient/PerServiceCallChatHistoryPersistingChatClient.cs

@@ -188,7 +188,7 @@ internal sealed class PerServiceCallChatHistoryPersistingChatClient : Delegating
         while (hasUpdates)
         {
             var update = enumerator.Current;
-            responseUpdates.Add(update);
+            responseUpdates.Add(update.Clone());
 
             // If the service returned a real ConversationId on any update, remember that.
             // Otherwise stamp our sentinel so FICC treats this as service-managed —

dotnet/src/Microsoft.Agents.AI/Compaction/ContextWindowCompactionStrategy.cs

@@ -0,0 +1,148 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.Logging;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI.Compaction;
+
+/// <summary>
+/// A compaction strategy that derives token thresholds from a model's context window size
+/// and maximum output tokens, applying a two-phase compaction pipeline:
+/// <list type="number">
+/// <item><description><b>Tool result eviction</b> (<see cref="ToolResultCompactionStrategy"/>) — collapses old tool call groups
+/// into concise summaries when the token count exceeds the <see cref="ToolEvictionThreshold"/>.</description></item>
+/// <item><description><b>Truncation</b> (<see cref="TruncationCompactionStrategy"/>) — removes the oldest non-system message groups
+/// when the token count exceeds the <see cref="TruncationThreshold"/>.</description></item>
+/// </list>
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <b>input budget</b> is defined as <c>maxContextWindowTokens - maxOutputTokens</c>, representing
+/// the maximum number of tokens available for the conversation input (including system messages, tools, and history).
+/// </para>
+/// <para>
+/// This strategy is a convenience wrapper around <see cref="PipelineCompactionStrategy"/> that automates
+/// threshold calculation from model specifications.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class ContextWindowCompactionStrategy : CompactionStrategy
+{
+    /// <summary>
+    /// The default fraction of the input budget at which tool result eviction triggers.
+    /// </summary>
+    public const double DefaultToolEvictionThreshold = 0.5;
+
+    /// <summary>
+    /// The default fraction of the input budget at which truncation triggers.
+    /// </summary>
+    public const double DefaultTruncationThreshold = 0.8;
+
+    private readonly PipelineCompactionStrategy _pipeline;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ContextWindowCompactionStrategy"/> class.
+    /// </summary>
+    /// <param name="maxContextWindowTokens">
+    /// The maximum number of tokens the model's context window supports (e.g., 1,050,000 for gpt-5.4).
+    /// </param>
+    /// <param name="maxOutputTokens">
+    /// The maximum number of output tokens the model can generate per response (e.g., 128,000 for gpt-5.4).
+    /// </param>
+    /// <param name="toolEvictionThreshold">
+    /// The fraction of the input budget (0.0, 1.0] at which tool result eviction triggers.
+    /// Defaults to <see cref="DefaultToolEvictionThreshold"/> (0.5).
+    /// </param>
+    /// <param name="truncationThreshold">
+    /// The fraction of the input budget (0.0, 1.0] at which truncation triggers.
+    /// Defaults to <see cref="DefaultTruncationThreshold"/> (0.8).
+    /// Must be greater than or equal to <paramref name="toolEvictionThreshold"/>.
+    /// </param>
+    /// <exception cref="ArgumentOutOfRangeException">
+    /// <paramref name="maxContextWindowTokens"/> is not positive, or
+    /// <paramref name="maxOutputTokens"/> is negative or greater than or equal to <paramref name="maxContextWindowTokens"/>, or
+    /// <paramref name="toolEvictionThreshold"/> or <paramref name="truncationThreshold"/> is not in (0.0, 1.0], or
+    /// <paramref name="truncationThreshold"/> is less than <paramref name="toolEvictionThreshold"/>.
+    /// </exception>
+    public ContextWindowCompactionStrategy(
+        int maxContextWindowTokens,
+        int maxOutputTokens,
+        double toolEvictionThreshold = DefaultToolEvictionThreshold,
+        double truncationThreshold = DefaultTruncationThreshold)
+        : base(CompactionTriggers.Always)
+    {
+        Throw.IfLessThanOrEqual(maxContextWindowTokens, 0);
+        Throw.IfLessThan(maxOutputTokens, 0);
+        Throw.IfGreaterThanOrEqual(maxOutputTokens, maxContextWindowTokens);
+
+        ValidateThreshold(toolEvictionThreshold, nameof(toolEvictionThreshold));
+        ValidateThreshold(truncationThreshold, nameof(truncationThreshold));
+
+        if (truncationThreshold < toolEvictionThreshold)
+        {
+            throw new ArgumentOutOfRangeException(nameof(truncationThreshold), truncationThreshold,
+                $"Truncation threshold ({truncationThreshold}) must be greater than or equal to tool eviction threshold ({toolEvictionThreshold}).");
+        }
+
+        this.MaxContextWindowTokens = maxContextWindowTokens;
+        this.MaxOutputTokens = maxOutputTokens;
+        this.InputBudgetTokens = maxContextWindowTokens - maxOutputTokens;
+        this.ToolEvictionThreshold = toolEvictionThreshold;
+        this.TruncationThreshold = truncationThreshold;
+
+        int toolEvictionTokens = (int)(this.InputBudgetTokens * toolEvictionThreshold);
+        int truncationTokens = (int)(this.InputBudgetTokens * truncationThreshold);
+
+        this._pipeline = new PipelineCompactionStrategy(
+            new ToolResultCompactionStrategy(
+                trigger: CompactionTriggers.TokensExceed(toolEvictionTokens),
+                minimumPreservedGroups: 2),
+            new TruncationCompactionStrategy(
+                trigger: CompactionTriggers.TokensExceed(truncationTokens),
+                minimumPreservedGroups: 2));
+    }
+
+    /// <summary>
+    /// Gets the maximum context window size in tokens.
+    /// </summary>
+    public int MaxContextWindowTokens { get; }
+
+    /// <summary>
+    /// Gets the maximum output tokens per response.
+    /// </summary>
+    public int MaxOutputTokens { get; }
+
+    /// <summary>
+    /// Gets the computed input budget in tokens (<see cref="MaxContextWindowTokens"/> minus <see cref="MaxOutputTokens"/>).
+    /// </summary>
+    public int InputBudgetTokens { get; }
+
+    /// <summary>
+    /// Gets the fraction of the input budget at which tool result eviction triggers.
+    /// </summary>
+    public double ToolEvictionThreshold { get; }
+
+    /// <summary>
+    /// Gets the fraction of the input budget at which truncation triggers.
+    /// </summary>
+    public double TruncationThreshold { get; }
+
+    /// <inheritdoc/>
+    protected override async ValueTask<bool> CompactCoreAsync(CompactionMessageIndex index, ILogger logger, CancellationToken cancellationToken)
+    {
+        return await this._pipeline.CompactAsync(index, logger, cancellationToken).ConfigureAwait(false);
+    }
+
+    private static void ValidateThreshold(double value, string paramName)
+    {
+        if (value is <= 0.0 or > 1.0)
+        {
+            throw new ArgumentOutOfRangeException(paramName, value, "Threshold must be in the range (0.0, 1.0].");
+        }
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProvider.cs

@@ -0,0 +1,244 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that tracks the agent's operating mode (e.g., "plan" or "execute")
+/// in the session state and provides tools for querying and switching modes.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="AgentModeProvider"/> enables agents to operate in distinct modes during long-running
+/// complex tasks. The current mode is persisted in the session's <see cref="AgentSessionStateBag"/>
+/// and is included in the instructions provided to the agent on each invocation.
+/// </para>
+/// <para>
+/// The set of available modes is configurable via <see cref="AgentModeProviderOptions.Modes"/>.
+/// By default, two modes are provided: <c>"plan"</c> (interactive planning) and <c>"execute"</c>
+/// (autonomous execution).
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>AgentMode_Set</c> — Switch the agent's operating mode.</description></item>
+/// <item><description><c>AgentMode_Get</c> — Retrieve the agent's current operating mode.</description></item>
+/// </list>
+/// </para>
+/// <para>
+/// Public helper methods <see cref="GetMode"/> and <see cref="SetMode"/> allow external code
+/// to programmatically read and change the mode.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class AgentModeProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## Agent Mode
+
+        You can operate in different modes. Depending on the mode you are in, you will be required to follow different processes.
+
+        Use the AgentMode_Get tool to check your current operating mode.
+        Use the AgentMode_Set tool to switch between modes as your work progresses. Only use AgentMode_Set if the user explicitly instructs/allows you to change modes.
+
+        {available_modes}
+
+        You are currently operating in the {current_mode} mode.
+        """;
+
+    private static readonly IReadOnlyList<AgentModeProviderOptions.AgentMode> s_defaultModes =
+    [
+        new("plan", "Use this mode when analyzing requirements, breaking down tasks, and creating plans. This is the interactive mode — ask clarifying questions, discuss options, and get user approval before proceeding."),
+        new("execute", "Use this mode when carrying out approved plans. Work autonomously using your best judgement — do not ask the user questions or wait for feedback. Make reasonable decisions on your own so that there is a complete, useful result when the user returns. If you encounter ambiguity, choose the most reasonable option and note your choice."),
+    ];
+
+    private readonly ProviderSessionState<AgentModeState> _sessionState;
+    private readonly IReadOnlyList<AgentModeProviderOptions.AgentMode> _modes;
+    private readonly string _defaultMode;
+    private readonly string? _instructions;
+    private readonly HashSet<string> _validModeNames;
+    private readonly string _modeNamesDisplay;
+    private IReadOnlyList<string>? _stateKeys;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AgentModeProvider"/> class.
+    /// </summary>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    public AgentModeProvider(AgentModeProviderOptions? options = null)
+    {
+        this._modes = options?.Modes ?? s_defaultModes;
+
+        if (this._modes.Count == 0)
+        {
+            throw new ArgumentException("At least one mode must be configured.", nameof(options));
+        }
+
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+
+        this._validModeNames = new HashSet<string>(StringComparer.Ordinal);
+        var modeNamesList = new List<string>(this._modes.Count);
+        for (int i = 0; i < this._modes.Count; i++)
+        {
+            var mode = this._modes[i];
+            if (mode is null)
+            {
+                throw new ArgumentException($"Configured mode at index {i} must not be null.", nameof(options));
+            }
+
+            if (string.IsNullOrEmpty(mode.Name))
+            {
+                throw new ArgumentException($"Configured mode at index {i} must have a non-empty name.", nameof(options));
+            }
+
+            if (!this._validModeNames.Add(mode.Name))
+            {
+                throw new ArgumentException($"Configured modes contain a duplicate mode name \"{mode.Name}\".", nameof(options));
+            }
+
+            modeNamesList.Add(mode.Name);
+        }
+
+        this._modeNamesDisplay = string.Join("\", \"", modeNamesList);
+        this._defaultMode = options?.DefaultMode ?? modeNamesList[0];
+
+        if (!this._validModeNames.Contains(this._defaultMode))
+        {
+            throw new ArgumentException($"Default mode \"{this._defaultMode}\" is not in the configured modes list.", nameof(options));
+        }
+
+        this._sessionState = new ProviderSessionState<AgentModeState>(
+            _ => new AgentModeState { CurrentMode = this._defaultMode },
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
+
+    /// <summary>
+    /// Gets the current operating mode from the session state.
+    /// </summary>
+    /// <param name="session">The agent session to read the mode from.</param>
+    /// <returns>The current mode string.</returns>
+    public string GetMode(AgentSession? session)
+    {
+        return this._sessionState.GetOrInitializeState(session).CurrentMode;
+    }
+
+    /// <summary>
+    /// Sets the operating mode in the session state.
+    /// </summary>
+    /// <param name="session">The agent session to update the mode in.</param>
+    /// <param name="mode">The new mode to set.</param>
+    /// <exception cref="ArgumentException"><paramref name="mode"/> is not a configured mode.</exception>
+    public void SetMode(AgentSession? session, string mode)
+    {
+        this.ValidateMode(mode);
+
+        AgentModeState state = this._sessionState.GetOrInitializeState(session);
+        string previousMode = state.CurrentMode;
+        state.CurrentMode = mode;
+
+        if (!string.Equals(previousMode, mode, StringComparison.Ordinal))
+        {
+            state.PreviousModeForNotification = previousMode;
+        }
+
+        this._sessionState.SaveState(session, state);
+    }
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        AgentModeState state = this._sessionState.GetOrInitializeState(context.Session);
+
+        string instructions = this.BuildInstructions(state.CurrentMode);
+
+        var aiContext = new AIContext
+        {
+            Instructions = instructions,
+            Tools = this.CreateTools(state, context.Session),
+        };
+
+        // If the mode was changed externally (e.g., via /mode command), inject a notification message
+        // so the agent clearly sees the change rather than relying solely on the system instructions.
+        if (state.PreviousModeForNotification != null)
+        {
+            string previousMode = state.PreviousModeForNotification;
+            state.PreviousModeForNotification = null;
+
+            aiContext.Messages =
+            [
+                new ChatMessage(ChatRole.User, $"[Mode changed: The operating mode has been switched from \"{previousMode}\" to \"{state.CurrentMode}\". You must now adjust your behavior to match the \"{state.CurrentMode}\" mode.]"),
+            ];
+        }
+
+        return new ValueTask<AIContext>(aiContext);
+    }
+
+    private string BuildInstructions(string currentMode)
+    {
+        // Build list of modes text:
+        var modesListBuilder = new StringBuilder();
+        foreach (var mode in this._modes)
+        {
+            modesListBuilder.AppendLine($"- \"{mode.Name}\": {mode.Description}");
+        }
+        var modesListText = modesListBuilder.ToString();
+
+        return new StringBuilder(this._instructions)
+            .Replace("{available_modes}", modesListText)
+            .Replace("{current_mode}", currentMode)
+            .ToString();
+    }
+
+    private void ValidateMode(string mode)
+    {
+        if (!this._validModeNames.Contains(mode))
+        {
+            throw new ArgumentException($"Invalid mode: \"{mode}\". Supported modes are: \"{this._modeNamesDisplay}\".", nameof(mode));
+        }
+    }
+
+    private AITool[] CreateTools(AgentModeState state, AgentSession? session)
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(
+                (string mode) =>
+                {
+                    this.ValidateMode(mode);
+
+                    state.CurrentMode = mode;
+                    this._sessionState.SaveState(session, state);
+                    return $"Mode changed to \"{mode}\".";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "AgentMode_Set",
+                    Description = $"Switch the agent's operating mode. Supported modes: \"{this._modeNamesDisplay}\".",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () => state.CurrentMode,
+                new AIFunctionFactoryOptions
+                {
+                    Name = "AgentMode_Get",
+                    Description = "Get the agent's current operating mode.",
+                    SerializerOptions = serializerOptions,
+                }),
+        ];
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeProviderOptions.cs

@@ -0,0 +1,77 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="AgentModeProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class AgentModeProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the mode tools.
+    /// </summary>
+    /// <remarks>
+    /// The instructions must contain a <c>{available_modes}</c> placeholder for the provider to inject the
+    /// currently available list of modes, and a <c>{current_mode}</c> placeholder to inject the currently
+    /// active mode.
+    /// </remarks>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses a default set of instructions.
+    /// </value>
+    public string? Instructions { get; set; }
+
+    /// <summary>
+    /// Gets or sets the list of available modes the agent can operate in.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses two built-in modes:
+    /// <c>"plan"</c> (interactive planning) and <c>"execute"</c> (autonomous execution).
+    /// </value>
+    public IReadOnlyList<AgentMode>? Modes { get; set; }
+
+    /// <summary>
+    /// Gets or sets the initial mode for new sessions.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the first mode in the <see cref="Modes"/> list is used.
+    /// Must match the <see cref="AgentMode.Name"/> of one of the configured modes.
+    /// </value>
+    public string? DefaultMode { get; set; }
+
+    /// <summary>
+    /// Represents an agent operating mode with a name and description.
+    /// </summary>
+    [Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+    public sealed class AgentMode
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="AgentMode"/> class.
+        /// </summary>
+        /// <param name="name">The name of the mode.</param>
+        /// <param name="description">A description of when and how to use this mode.</param>
+        /// <exception cref="ArgumentNullException"><paramref name="name"/> or <paramref name="description"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException"><paramref name="name"/> or <paramref name="description"/> is empty or whitespace.</exception>
+        public AgentMode(string name, string description)
+        {
+            this.Name = Throw.IfNullOrWhitespace(name);
+            this.Description = Throw.IfNullOrWhitespace(description);
+        }
+
+        /// <summary>
+        /// Gets the name of the mode.
+        /// </summary>
+        public string Name { get; }
+
+        /// <summary>
+        /// Gets a description of when and how to use this mode.
+        /// </summary>
+        public string Description { get; }
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/AgentMode/AgentModeState.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the state of the agent's operating mode, stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class AgentModeState
+{
+    /// <summary>
+    /// Gets or sets the current operating mode of the agent.
+    /// </summary>
+    [JsonPropertyName("currentMode")]
+    public string CurrentMode { get; set; } = "plan";
+
+    /// <summary>
+    /// Gets or sets the previous mode before the last external change, if a mode change notification is pending.
+    /// When non-null, indicates that the mode was changed externally and a notification should be injected.
+    /// </summary>
+    [JsonPropertyName("previousModeForNotification")]
+    public string? PreviousModeForNotification { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileAccess/FileAccessProvider.cs

@@ -0,0 +1,180 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that provides file access tools to an agent
+/// for saving, reading, deleting, listing, and searching files.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="FileAccessProvider"/> gives agents the ability to work with files
+/// in a folder that the user has granted access to. Unlike <see cref="FileMemoryProvider"/>,
+/// which provides session-scoped memory that may be isolated per session, <see cref="FileAccessProvider"/>
+/// operates on a shared, persistent folder whose contents are visible across sessions and agents.
+/// This makes it suitable for reading input data, writing output artifacts, and working with
+/// files that have a lifetime beyond any single agent session.
+/// </para>
+/// <para>
+/// File access is mediated through a <see cref="AgentFileStore"/> abstraction, allowing pluggable
+/// backends (in-memory, local file system, remote blob storage, etc.).
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>SaveFile</c> — Save a file with the given name and content.</description></item>
+/// <item><description><c>ReadFile</c> — Read the content of a file by name.</description></item>
+/// <item><description><c>DeleteFile</c> — Delete a file by name.</description></item>
+/// <item><description><c>ListFiles</c> — List all file names.</description></item>
+/// <item><description><c>SearchFiles</c> — Search file contents using a regular expression pattern.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAccessProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## File Access
+        You have access to a shared file storage area via the `FileAccess_*` tools for reading, writing, and managing files.
+        These files persist beyond the current session and may be shared across sessions or agents.
+        Use these tools to read input data provided by the user, write output artifacts, and manage any files the user has asked you to work with.
+
+        - Never delete or overwrite existing files unless the user has explicitly asked you to do so.
+        """;
+
+    private readonly AgentFileStore _fileStore;
+    private readonly string _instructions;
+    private AITool[]? _tools;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileAccessProvider"/> class.
+    /// </summary>
+    /// <param name="fileStore">
+    /// The file store implementation used for storage operations.
+    /// The store should already be scoped to the desired folder or storage location.
+    /// </param>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    /// <exception cref="System.ArgumentNullException">Thrown when <paramref name="fileStore"/> is <see langword="null"/>.</exception>
+    public FileAccessProvider(AgentFileStore fileStore, FileAccessProviderOptions? options = null)
+    {
+        Throw.IfNull(fileStore);
+
+        this._fileStore = fileStore;
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => [];
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        return new ValueTask<AIContext>(new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this._tools ??= this.CreateTools(),
+        });
+    }
+
+    /// <summary>
+    /// Save a file with the given name and content. By default, does not overwrite an existing file unless overwrite is set to true.
+    /// </summary>
+    /// <param name="fileName">The name of the file to save.</param>
+    /// <param name="content">The content to write to the file.</param>
+    /// <param name="overwrite">Whether to overwrite the file if it already exists.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation message.</returns>
+    [Description("Save a file with the given name and content. By default, does not overwrite an existing file unless overwrite is set to true.")]
+    private async Task<string> SaveFileAsync(string fileName, string content, bool overwrite = false, CancellationToken cancellationToken = default)
+    {
+        string path = StorePaths.NormalizeRelativePath(fileName);
+
+        if (!overwrite && await this._fileStore.FileExistsAsync(path, cancellationToken).ConfigureAwait(false))
+        {
+            return $"File '{fileName}' already exists. To replace it, save again with overwrite set to true.";
+        }
+
+        await this._fileStore.WriteFileAsync(path, content, cancellationToken).ConfigureAwait(false);
+        return $"File '{fileName}' saved.";
+    }
+
+    /// <summary>
+    /// Read the content of a file by name. Returns the file content or a message indicating the file was not found.
+    /// </summary>
+    /// <param name="fileName">The name of the file to read.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>The file content or a not-found message.</returns>
+    [Description("Read the content of a file by name. Returns the file content or a message indicating the file was not found.")]
+    private async Task<string> ReadFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        string path = StorePaths.NormalizeRelativePath(fileName);
+        string? content = await this._fileStore.ReadFileAsync(path, cancellationToken).ConfigureAwait(false);
+        return content ?? $"File '{fileName}' not found.";
+    }
+
+    /// <summary>
+    /// Delete a file by name.
+    /// </summary>
+    /// <param name="fileName">The name of the file to delete.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation or not-found message.</returns>
+    [Description("Delete a file by name.")]
+    private async Task<string> DeleteFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        string path = StorePaths.NormalizeRelativePath(fileName);
+        bool deleted = await this._fileStore.DeleteFileAsync(path, cancellationToken).ConfigureAwait(false);
+        return deleted ? $"File '{fileName}' deleted." : $"File '{fileName}' not found.";
+    }
+
+    /// <summary>
+    /// List all file names.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of file names.</returns>
+    [Description("List all file names.")]
+    private async Task<List<string>> ListFilesAsync(CancellationToken cancellationToken = default)
+    {
+        IReadOnlyList<string> fileNames = await this._fileStore.ListFilesAsync(string.Empty, cancellationToken).ConfigureAwait(false);
+        return new List<string>(fileNames);
+    }
+
+    /// <summary>
+    /// Search file contents using a regular expression pattern (case-insensitive).
+    /// Optionally filter which files to search using a glob pattern.
+    /// </summary>
+    /// <param name="regexPattern">A regular expression pattern to match against file contents (case-insensitive).</param>
+    /// <param name="filePattern">An optional glob pattern to filter which files to search (e.g., "*.md", "research*"). Leave empty or omit to search all files.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of search results with matching file names, snippets, and matching lines.</returns>
+    [Description("Search file contents using a regular expression pattern (case-insensitive). Optionally filter which files to search using a glob pattern (e.g., \"*.md\", \"research*\"). Returns matching file names, snippets, and matching lines with line numbers.")]
+    private async Task<List<FileSearchResult>> SearchFilesAsync(string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default)
+    {
+        string? pattern = string.IsNullOrWhiteSpace(filePattern) ? null : filePattern;
+        IReadOnlyList<FileSearchResult> results = await this._fileStore.SearchFilesAsync(string.Empty, regexPattern, pattern, cancellationToken).ConfigureAwait(false);
+        return new List<FileSearchResult>(results);
+    }
+
+    private AITool[] CreateTools()
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(this.SaveFileAsync, new AIFunctionFactoryOptions { Name = "FileAccess_SaveFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ReadFileAsync, new AIFunctionFactoryOptions { Name = "FileAccess_ReadFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.DeleteFileAsync, new AIFunctionFactoryOptions { Name = "FileAccess_DeleteFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ListFilesAsync, new AIFunctionFactoryOptions { Name = "FileAccess_ListFiles", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.SearchFilesAsync, new AIFunctionFactoryOptions { Name = "FileAccess_SearchFiles", SerializerOptions = serializerOptions }),
+        ];
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileAccess/FileAccessProviderOptions.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="FileAccessProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileAccessProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the file access tools.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to use file storage effectively.
+    /// </value>
+    public string? Instructions { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileListEntry.cs

@@ -0,0 +1,27 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a file entry returned by the <see cref="FileMemoryProvider"/> list files tool,
+/// containing the file name and an optional description.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileListEntry
+{
+    /// <summary>
+    /// Gets or sets the name of the file.
+    /// </summary>
+    [JsonPropertyName("fileName")]
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the description of the file, or <see langword="null"/> if no description is available.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string? Description { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProvider.cs

@@ -0,0 +1,425 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that provides file-based memory tools to an agent
+/// for storing, retrieving, modifying, listing, deleting, and searching files.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="FileMemoryProvider"/> enables agents to persist information across interactions
+/// using a file-based storage model. Each memory is stored as an individual file with a meaningful name.
+/// For large files, a companion description file (suffixed with <c>_description.md</c>) can be stored
+/// alongside the main file to provide a summary.
+/// </para>
+/// <para>
+/// File access is mediated through a <see cref="AgentFileStore"/> abstraction, allowing pluggable
+/// backends (in-memory, local file system, remote blob storage, etc.).
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>SaveFile</c> — Save a memory file with the given name, content, and an optional description.</description></item>
+/// <item><description><c>ReadFile</c> — Read the content of a file by name.</description></item>
+/// <item><description><c>DeleteFile</c> — Delete a file by name.</description></item>
+/// <item><description><c>ListFiles</c> — List all files with their descriptions (if available).</description></item>
+/// <item><description><c>SearchFiles</c> — Search file contents using a regular expression pattern.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileMemoryProvider : AIContextProvider, IDisposable
+{
+    private const string DescriptionSuffix = "_description.md";
+    private const string MemoryIndexFileName = "memories.md";
+    private const int MaxIndexEntries = 50;
+
+    private const string DefaultInstructions =
+        """
+        ## File Based Memory
+        You have access to a session-scoped, file-based memory system via the `FileMemory_*` tools for storing and retrieving information across interactions.
+        These files act as your working memory for the current session and are isolated from other sessions.
+        Use these tools to store plans, memories, processing results, or downloaded data.
+
+        - Use descriptive file names (e.g., "projectarchitecture.md", "userpreferences.md").
+        - Include a description when saving a file to help with future discovery.
+        - Before starting new tasks, use FileMemory_ListFiles and FileMemory_SearchFiles to check for relevant existing memories.
+        - Keep memories up-to-date by overwriting files when information changes.
+        - When you receive large amounts of data (e.g., downloaded web pages, API responses, research results),
+          save them to files if they will be required later, so that they are not lost when older context is compacted or truncated.
+          This ensures important data remains accessible across long-running sessions.
+        """;
+
+    private readonly AgentFileStore _fileStore;
+    private readonly ProviderSessionState<FileMemoryState> _sessionState;
+    private readonly SemaphoreSlim _writeLock = new(1, 1);
+    private readonly string _instructions;
+    private IReadOnlyList<string>? _stateKeys;
+    private AITool[]? _tools;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileMemoryProvider"/> class.
+    /// </summary>
+    /// <param name="fileStore">The file store implementation used for storage operations.</param>
+    /// <param name="stateInitializer">
+    /// An optional function that initializes the <see cref="FileMemoryState"/> for a new session.
+    /// Use this to customize the working folder (e.g., per-user or per-session subfolders).
+    /// When <see langword="null"/>, the default initializer creates state with an empty working folder.
+    /// </param>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    /// <exception cref="ArgumentNullException">Thrown when <paramref name="fileStore"/> is <see langword="null"/>.</exception>
+    public FileMemoryProvider(AgentFileStore fileStore, Func<AgentSession?, FileMemoryState>? stateInitializer = null, FileMemoryProviderOptions? options = null)
+    {
+        Throw.IfNull(fileStore);
+
+        this._fileStore = fileStore;
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+        this._sessionState = new ProviderSessionState<FileMemoryState>(
+            stateInitializer ?? (_ => new FileMemoryState()),
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
+
+    /// <summary>
+    /// Releases the resources used by the <see cref="FileMemoryProvider"/>.
+    /// </summary>
+    public void Dispose()
+    {
+        this._writeLock.Dispose();
+    }
+
+    /// <inheritdoc />
+    protected override async ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(context.Session);
+
+        // Ensure the working folder exists in the store.
+        if (!string.IsNullOrEmpty(state.WorkingFolder))
+        {
+            await this._fileStore.CreateDirectoryAsync(state.WorkingFolder, cancellationToken).ConfigureAwait(false);
+        }
+
+        var aiContext = new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this._tools ??= this.CreateTools(),
+        };
+
+        // Inject the memory index as a user message so the agent knows what memories are available.
+        string indexPath = CombinePaths(state.WorkingFolder, MemoryIndexFileName);
+        string? indexContent = await this._fileStore.ReadFileAsync(indexPath, cancellationToken).ConfigureAwait(false);
+        if (!string.IsNullOrWhiteSpace(indexContent))
+        {
+            aiContext.Messages =
+            [
+                new ChatMessage(ChatRole.User,
+                    "The following is your memory index — a list of files you have previously saved. " +
+                    "You can read any of these files using the FileMemory_ReadFile tool.\n\n" +
+                    indexContent),
+            ];
+        }
+
+        return aiContext;
+    }
+
+    /// <summary>
+    /// Save a memory file with the given name and content.
+    /// Overwrites the file if it already exists.
+    /// Include a description for large files to provide a summary that helps with discovery.
+    /// </summary>
+    /// <param name="fileName">The name of the file to save.</param>
+    /// <param name="content">The content to write to the file.</param>
+    /// <param name="description">An optional description of the file contents for discovery. Leave empty or omit to skip.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation message.</returns>
+    [Description("Save a memory file with the given name and content. Overwrites the file if it already exists. Include a description for large files to provide a summary that helps with discovery.")]
+    private async Task<string> SaveFileAsync(string fileName, string content, string? description = null, CancellationToken cancellationToken = default)
+    {
+        if (IsInternalFile(fileName))
+        {
+            throw new ArgumentException("The provided file name is reserved by the system for internal use. Please choose a different file name.", nameof(fileName));
+        }
+
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string path = ResolvePath(state.WorkingFolder, fileName);
+
+        await this._writeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            await this._fileStore.WriteFileAsync(path, content, cancellationToken).ConfigureAwait(false);
+
+            string descPath = ResolvePath(state.WorkingFolder, GetDescriptionFileName(fileName));
+
+            if (!string.IsNullOrWhiteSpace(description))
+            {
+                await this._fileStore.WriteFileAsync(descPath, description, cancellationToken).ConfigureAwait(false);
+            }
+            else
+            {
+                // Remove any stale description file when no description is provided.
+                await this._fileStore.DeleteFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+            }
+
+            string result = string.IsNullOrWhiteSpace(description)
+                ? $"File '{fileName}' saved."
+                : $"File '{fileName}' saved with description.";
+
+            await this.RebuildMemoryIndexAsync(state, cancellationToken).ConfigureAwait(false);
+            return result;
+        }
+        finally
+        {
+            this._writeLock.Release();
+        }
+    }
+
+    /// <summary>
+    /// Read the content of a memory file by name.
+    /// Returns the file content or a message indicating the file was not found.
+    /// </summary>
+    /// <param name="fileName">The name of the file to read.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>The file content or a not-found message.</returns>
+    [Description("Read the content of a memory file by name. Returns the file content or a message indicating the file was not found.")]
+    private async Task<string> ReadFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string path = ResolvePath(state.WorkingFolder, fileName);
+        string? content = await this._fileStore.ReadFileAsync(path, cancellationToken).ConfigureAwait(false);
+        return content ?? $"File '{fileName}' not found.";
+    }
+
+    /// <summary>
+    /// Delete a memory file by name. Also removes its companion description file if one exists.
+    /// </summary>
+    /// <param name="fileName">The name of the file to delete.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A confirmation or not-found message.</returns>
+    [Description("Delete a memory file by name. Also removes its companion description file if one exists.")]
+    private async Task<string> DeleteFileAsync(string fileName, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string path = ResolvePath(state.WorkingFolder, fileName);
+
+        await this._writeLock.WaitAsync(cancellationToken).ConfigureAwait(false);
+        try
+        {
+            bool deleted = await this._fileStore.DeleteFileAsync(path, cancellationToken).ConfigureAwait(false);
+
+            // Also delete companion description file if it exists.
+            string descPath = ResolvePath(state.WorkingFolder, GetDescriptionFileName(fileName));
+            await this._fileStore.DeleteFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+
+            await this.RebuildMemoryIndexAsync(state, cancellationToken).ConfigureAwait(false);
+            return deleted ? $"File '{fileName}' deleted." : $"File '{fileName}' not found.";
+        }
+        finally
+        {
+            this._writeLock.Release();
+        }
+    }
+
+    /// <summary>
+    /// List all memory files with their descriptions (if available). Description files are not shown separately.
+    /// </summary>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of file entries with names and optional descriptions.</returns>
+    [Description("List all memory files with their descriptions (if available). Description files are not shown separately.")]
+    private async Task<List<FileListEntry>> ListFilesAsync(CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        IReadOnlyList<string> fileNames = await this._fileStore.ListFilesAsync(state.WorkingFolder, cancellationToken).ConfigureAwait(false);
+
+        var descriptionFileSet = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+        foreach (string file in fileNames)
+        {
+            if (file.EndsWith(DescriptionSuffix, StringComparison.OrdinalIgnoreCase))
+            {
+                descriptionFileSet.Add(file);
+            }
+        }
+
+        var entries = new List<FileListEntry>();
+        foreach (string file in fileNames)
+        {
+            if (descriptionFileSet.Contains(file))
+            {
+                continue;
+            }
+
+            if (IsInternalFile(file))
+            {
+                continue;
+            }
+
+            string? fileDescription = null;
+            string descFileName = GetDescriptionFileName(file);
+
+            if (descriptionFileSet.Contains(descFileName))
+            {
+                string descPath = CombinePaths(state.WorkingFolder, descFileName);
+                fileDescription = await this._fileStore.ReadFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+            }
+
+            entries.Add(new FileListEntry { FileName = file, Description = fileDescription });
+        }
+
+        return entries;
+    }
+
+    /// <summary>
+    /// Search memory file contents using a regular expression pattern (case-insensitive).
+    /// Optionally filter which files to search using a glob pattern.
+    /// Returns matching file names, content snippets, and matching lines with line numbers.
+    /// </summary>
+    /// <param name="regexPattern">A regular expression pattern to match against file contents (case-insensitive).</param>
+    /// <param name="filePattern">An optional glob pattern to filter which files to search (e.g., "*.md", "research*"). Leave empty or omit to search all files.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of search results with matching file names, snippets, and matching lines.</returns>
+    [Description("Search memory file contents using a regular expression pattern (case-insensitive). Optionally filter which files to search using a glob pattern (e.g., \"*.md\", \"research*\"). Returns matching file names, content snippets, and matching lines with line numbers.")]
+    private async Task<List<FileSearchResult>> SearchFilesAsync(string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default)
+    {
+        FileMemoryState state = this._sessionState.GetOrInitializeState(AIAgent.CurrentRunContext?.Session);
+        string? pattern = string.IsNullOrWhiteSpace(filePattern) ? null : filePattern;
+        IReadOnlyList<FileSearchResult> results = await this._fileStore.SearchFilesAsync(state.WorkingFolder, regexPattern, pattern, cancellationToken).ConfigureAwait(false);
+
+        // Filter out internal files (description sidecars and memory index) so they stay hidden.
+        var filtered = new List<FileSearchResult>(results.Count);
+        foreach (var result in results)
+        {
+            if (IsInternalFile(result.FileName))
+            {
+                continue;
+            }
+
+            filtered.Add(result);
+        }
+
+        return filtered;
+    }
+
+    private AITool[] CreateTools()
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(this.SaveFileAsync, new AIFunctionFactoryOptions { Name = "FileMemory_SaveFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ReadFileAsync, new AIFunctionFactoryOptions { Name = "FileMemory_ReadFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.DeleteFileAsync, new AIFunctionFactoryOptions { Name = "FileMemory_DeleteFile", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.ListFilesAsync, new AIFunctionFactoryOptions { Name = "FileMemory_ListFiles", SerializerOptions = serializerOptions }),
+            AIFunctionFactory.Create(this.SearchFilesAsync, new AIFunctionFactoryOptions { Name = "FileMemory_SearchFiles", SerializerOptions = serializerOptions }),
+        ];
+    }
+
+    /// <summary>
+    /// Rebuilds the <c>memories.md</c> index file by listing all user files in the working folder,
+    /// reading their companion description files, and writing a markdown summary capped at <see cref="MaxIndexEntries"/> entries.
+    /// </summary>
+    private async Task RebuildMemoryIndexAsync(FileMemoryState state, CancellationToken cancellationToken)
+    {
+        IReadOnlyList<string> fileNames = await this._fileStore.ListFilesAsync(state.WorkingFolder, cancellationToken).ConfigureAwait(false);
+
+        // Sort deterministically so the index is stable across runs and platforms.
+        var sortedFiles = fileNames.OrderBy(f => f, StringComparer.OrdinalIgnoreCase).ToList();
+
+        var sb = new System.Text.StringBuilder();
+        sb.AppendLine("# Memory Index");
+        sb.AppendLine();
+
+        int count = 0;
+        foreach (string file in sortedFiles)
+        {
+            // Skip internal system files.
+            if (IsInternalFile(file))
+            {
+                continue;
+            }
+
+            if (count >= MaxIndexEntries)
+            {
+                break;
+            }
+
+            string? description = null;
+            string descFileName = GetDescriptionFileName(file);
+            string descPath = CombinePaths(state.WorkingFolder, descFileName);
+            description = await this._fileStore.ReadFileAsync(descPath, cancellationToken).ConfigureAwait(false);
+
+            if (!string.IsNullOrWhiteSpace(description))
+            {
+                sb.AppendLine($"- **{file}**: {description}");
+            }
+            else
+            {
+                sb.AppendLine($"- **{file}**");
+            }
+
+            count++;
+        }
+
+        string indexPath = CombinePaths(state.WorkingFolder, MemoryIndexFileName);
+        await this._fileStore.WriteFileAsync(indexPath, sb.ToString(), cancellationToken).ConfigureAwait(false);
+    }
+
+    private static string GetDescriptionFileName(string fileName)
+    {
+        int extIndex = fileName.LastIndexOf('.');
+        if (extIndex > 0)
+        {
+#pragma warning disable CA1845 // Use span-based 'string.Concat' — not available on all target frameworks
+            return fileName.Substring(0, extIndex) + DescriptionSuffix;
+#pragma warning restore CA1845
+        }
+
+        return fileName + DescriptionSuffix;
+    }
+
+    /// <summary>
+    /// Returns <see langword="true"/> if the file is an internal system file that should be hidden
+    /// from user-facing operations (description sidecars and the memory index).
+    /// </summary>
+    private static bool IsInternalFile(string fileName) =>
+        fileName.EndsWith(DescriptionSuffix, StringComparison.OrdinalIgnoreCase) ||
+        fileName.Equals(MemoryIndexFileName, StringComparison.OrdinalIgnoreCase);
+
+    private static string ResolvePath(string workingFolder, string fileName)
+    {
+        // Validate and normalize the file name (rejects rooted, traversal, empty, etc.).
+        // Only fileName needs validation — workingFolder is developer-provided and trusted.
+        string normalizedFileName = StorePaths.NormalizeRelativePath(fileName);
+
+        string normalizedWorkingFolder = workingFolder.Replace('\\', '/');
+        return CombinePaths(normalizedWorkingFolder, normalizedFileName);
+    }
+
+    private static string CombinePaths(string basePath, string relativePath)
+    {
+        if (string.IsNullOrEmpty(basePath))
+        {
+            return relativePath;
+        }
+
+        if (string.IsNullOrEmpty(relativePath))
+        {
+            return basePath;
+        }
+
+        return basePath.TrimEnd('/') + "/" + relativePath.TrimStart('/');
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryProviderOptions.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="FileMemoryProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileMemoryProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the file memory tools.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to use file-based memory effectively.
+    /// </value>
+    public string? Instructions { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileMemory/FileMemoryState.cs

@@ -0,0 +1,21 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the state of the <see cref="FileMemoryProvider"/>,
+/// stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileMemoryState
+{
+    /// <summary>
+    /// Gets or sets the working folder path for this session, relative to the store root.
+    /// </summary>
+    [JsonPropertyName("workingFolder")]
+    public string WorkingFolder { get; set; } = string.Empty;
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/AgentFileStore.cs

@@ -0,0 +1,93 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.FileSystemGlobbing;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Provides an abstract base class for file storage operations.
+/// </summary>
+/// <remarks>
+/// <para>
+/// All paths are relative to an implementation-defined root. Implementations may map these
+/// paths to a local file system, in-memory store, remote blob storage, or other mechanisms.
+/// </para>
+/// <para>
+/// Paths use forward slashes as separators and must not escape the root (e.g., via <c>..</c> segments).
+/// It is up to each implementation to ensure that this is enforced.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public abstract class AgentFileStore
+{
+    /// <summary>
+    /// Writes content to a file, creating or overwriting it.
+    /// </summary>
+    /// <param name="path">The relative path of the file to write.</param>
+    /// <param name="content">The content to write to the file.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    public abstract Task WriteFileAsync(string path, string content, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Reads the content of a file.
+    /// </summary>
+    /// <param name="path">The relative path of the file to read.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>The file content, or <see langword="null"/> if the file does not exist.</returns>
+    public abstract Task<string?> ReadFileAsync(string path, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Deletes a file.
+    /// </summary>
+    /// <param name="path">The relative path of the file to delete.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns><see langword="true"/> if the file was deleted; <see langword="false"/> if it did not exist.</returns>
+    public abstract Task<bool> DeleteFileAsync(string path, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Lists files in a directory.
+    /// </summary>
+    /// <param name="directory">The relative path of the directory to list. Use an empty string for the root.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of file names in the specified directory (direct children only).</returns>
+    public abstract Task<IReadOnlyList<string>> ListFilesAsync(string directory, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Checks whether a file exists.
+    /// </summary>
+    /// <param name="path">The relative path of the file to check.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns><see langword="true"/> if the file exists; otherwise, <see langword="false"/>.</returns>
+    public abstract Task<bool> FileExistsAsync(string path, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Searches for files whose content matches a regular expression pattern.
+    /// </summary>
+    /// <param name="directory">The relative path of the directory to search. Use an empty string for the root.</param>
+    /// <param name="regexPattern">
+    /// A regular expression pattern to match against file contents. The pattern is matched case-insensitively.
+    /// For example, <c>"error|warning"</c> matches lines containing "error" or "warning".
+    /// </param>
+    /// <param name="filePattern">
+    /// An optional glob pattern to filter which files are searched (e.g., <c>"*.md"</c>, <c>"research*"</c>).
+    /// When <see langword="null"/>, all files in the directory are searched.
+    /// Uses standard glob syntax from <see cref="Matcher"/>.
+    /// </param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A list of search results with matching file names, snippets, and matching lines.</returns>
+    public abstract Task<IReadOnlyList<FileSearchResult>> SearchFilesAsync(string directory, string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Ensures a directory exists, creating it if necessary.
+    /// </summary>
+    /// <param name="path">The relative path of the directory to create.</param>
+    /// <param name="cancellationToken">A token to cancel the operation.</param>
+    /// <returns>A task representing the asynchronous operation.</returns>
+    public abstract Task CreateDirectoryAsync(string path, CancellationToken cancellationToken = default);
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/FileSearchMatch.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a match found within a file during a search operation.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileSearchMatch
+{
+    /// <summary>
+    /// Gets or sets the 1-based line number where the match was found.
+    /// </summary>
+    [JsonPropertyName("lineNumber")]
+    public int LineNumber { get; set; }
+
+    /// <summary>
+    /// Gets or sets the content of the matching line.
+    /// </summary>
+    [JsonPropertyName("line")]
+    public string Line { get; set; } = string.Empty;
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/FileSearchResult.cs

@@ -0,0 +1,33 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a result from searching files, containing the file name, a content snippet, and matching lines.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileSearchResult
+{
+    /// <summary>
+    /// Gets or sets the name of the file that matched the search.
+    /// </summary>
+    [JsonPropertyName("fileName")]
+    public string FileName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets a snippet of content from the file around the first match.
+    /// </summary>
+    [JsonPropertyName("snippet")]
+    public string Snippet { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the lines where matches were found.
+    /// </summary>
+    [JsonPropertyName("matchingLines")]
+    public List<FileSearchMatch> MatchingLines { get; set; } = [];
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/FileSystemAgentFileStore.cs

@@ -0,0 +1,269 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.IO;
+using System.Linq;
+using System.Text;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.FileSystemGlobbing;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A file-system-backed implementation of <see cref="AgentFileStore"/> that stores files on disk
+/// under a configurable root directory.
+/// </summary>
+/// <remarks>
+/// <para>
+/// All paths passed to this store are resolved relative to the root directory provided
+/// at construction time. Lexical path traversal attempts (for example, via <c>..</c> segments
+/// or absolute paths) are rejected with an <see cref="ArgumentException"/>.
+/// </para>
+/// <para>
+/// The root directory is created automatically if it does not already exist.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class FileSystemAgentFileStore : AgentFileStore
+{
+    /// <summary>
+    /// The canonical full path of the root directory, always ending with a directory separator.
+    /// </summary>
+    private readonly string _rootPath;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="FileSystemAgentFileStore"/> class.
+    /// </summary>
+    /// <param name="rootDirectory">
+    /// The root directory under which all files are stored. Created if it does not exist.
+    /// </param>
+    public FileSystemAgentFileStore(string rootDirectory)
+    {
+        _ = Throw.IfNullOrWhitespace(rootDirectory);
+
+        // Canonicalize the root and ensure it ends with a separator for prefix comparison.
+        string fullRoot = Path.GetFullPath(rootDirectory);
+        if (!fullRoot.EndsWith(Path.DirectorySeparatorChar.ToString(), StringComparison.Ordinal) &&
+            !fullRoot.EndsWith(Path.AltDirectorySeparatorChar.ToString(), StringComparison.Ordinal))
+        {
+            fullRoot += Path.DirectorySeparatorChar;
+        }
+
+        this._rootPath = fullRoot;
+        Directory.CreateDirectory(fullRoot);
+    }
+
+    /// <inheritdoc />
+    public override async Task WriteFileAsync(string path, string content, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+
+        // Ensure the parent directory exists.
+        string? parentDir = Path.GetDirectoryName(fullPath);
+        if (parentDir is not null)
+        {
+            Directory.CreateDirectory(parentDir);
+        }
+
+#if NET8_0_OR_GREATER
+        await File.WriteAllTextAsync(fullPath, content, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
+#else
+        using var writer = new StreamWriter(fullPath, false, Encoding.UTF8);
+        await writer.WriteAsync(content).ConfigureAwait(false);
+#endif
+    }
+
+    /// <inheritdoc />
+    public override async Task<string?> ReadFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+
+        if (!File.Exists(fullPath))
+        {
+            return null;
+        }
+
+#if NET8_0_OR_GREATER
+        return await File.ReadAllTextAsync(fullPath, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
+#else
+        using var reader = new StreamReader(fullPath, Encoding.UTF8);
+        return await reader.ReadToEndAsync().ConfigureAwait(false);
+#endif
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> DeleteFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+
+        if (!File.Exists(fullPath))
+        {
+            return Task.FromResult(false);
+        }
+
+        File.Delete(fullPath);
+        return Task.FromResult(true);
+    }
+
+    /// <inheritdoc />
+    public override Task<IReadOnlyList<string>> ListFilesAsync(string directory, CancellationToken cancellationToken = default)
+    {
+        string fullDir = this.ResolveSafeDirectoryPath(directory);
+
+        if (!Directory.Exists(fullDir))
+        {
+            return Task.FromResult<IReadOnlyList<string>>([]);
+        }
+
+        var files = Directory.GetFiles(fullDir)
+            .Select(Path.GetFileName)
+            .Where(name => name is not null)
+            .ToList();
+
+        return Task.FromResult<IReadOnlyList<string>>(files!);
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> FileExistsAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafePath(path);
+        return Task.FromResult(File.Exists(fullPath));
+    }
+
+    /// <inheritdoc />
+    public override async Task<IReadOnlyList<FileSearchResult>> SearchFilesAsync(
+        string directory,
+        string regexPattern,
+        string? filePattern = null,
+        CancellationToken cancellationToken = default)
+    {
+        string fullDir = this.ResolveSafeDirectoryPath(directory);
+
+        if (!Directory.Exists(fullDir))
+        {
+            return [];
+        }
+
+        // Compile the regex with a timeout to guard against catastrophic backtracking (ReDoS).
+        var regex = new Regex(regexPattern, RegexOptions.IgnoreCase, TimeSpan.FromSeconds(5));
+        Matcher? matcher = filePattern is not null ? StorePaths.CreateGlobMatcher(filePattern) : null;
+        var results = new List<FileSearchResult>();
+
+        foreach (string filePath in Directory.GetFiles(fullDir))
+        {
+            string? fileName = Path.GetFileName(filePath);
+            if (fileName is null)
+            {
+                continue;
+            }
+
+            // Apply the optional glob filter on the file name.
+            if (!StorePaths.MatchesGlob(fileName, matcher))
+            {
+                continue;
+            }
+
+            // Read file content.
+#if NET8_0_OR_GREATER
+            string fileContent = await File.ReadAllTextAsync(filePath, Encoding.UTF8, cancellationToken).ConfigureAwait(false);
+#else
+            string fileContent;
+            using (var reader = new StreamReader(filePath, Encoding.UTF8))
+            {
+                fileContent = await reader.ReadToEndAsync().ConfigureAwait(false);
+            }
+#endif
+
+            // Search each line for regex matches, tracking line numbers and building a snippet.
+            string[] lines = fileContent.Split('\n');
+            var matchingLines = new List<FileSearchMatch>();
+            string? firstSnippet = null;
+            int lineStartOffset = 0;
+
+            for (int i = 0; i < lines.Length; i++)
+            {
+                Match match = regex.Match(lines[i]);
+                if (match.Success)
+                {
+                    matchingLines.Add(new FileSearchMatch { LineNumber = i + 1, Line = lines[i].TrimEnd('\r') });
+
+                    // Build a context snippet around the first match (±50 chars).
+                    if (firstSnippet is null)
+                    {
+                        int charIndex = lineStartOffset + match.Index;
+                        int snippetStart = Math.Max(0, charIndex - 50);
+                        int snippetEnd = Math.Min(fileContent.Length, charIndex + match.Value.Length + 50);
+                        firstSnippet = fileContent.Substring(snippetStart, snippetEnd - snippetStart);
+                    }
+                }
+
+                // Advance the offset past this line (including the '\n' separator).
+                lineStartOffset += lines[i].Length + 1;
+            }
+
+            if (matchingLines.Count > 0)
+            {
+                results.Add(new FileSearchResult
+                {
+                    FileName = fileName,
+                    Snippet = firstSnippet!,
+                    MatchingLines = matchingLines,
+                });
+            }
+        }
+
+        return results;
+    }
+
+    /// <inheritdoc />
+    public override Task CreateDirectoryAsync(string path, CancellationToken cancellationToken = default)
+    {
+        string fullPath = this.ResolveSafeDirectoryPath(path);
+        Directory.CreateDirectory(fullPath);
+        return Task.CompletedTask;
+    }
+
+    /// <summary>
+    /// Resolves a relative file path to a safe absolute path under the root directory.
+    /// Rejects paths that would escape the root via traversal or rooted paths.
+    /// </summary>
+    private string ResolveSafePath(string relativePath)
+    {
+        // Normalize and validate the relative path (rejects rooted, traversal, etc.).
+        string normalized = StorePaths.NormalizeRelativePath(relativePath);
+
+        // Convert to OS-native separators before combining.
+        string nativePath = normalized.Replace('/', Path.DirectorySeparatorChar);
+        string combined = Path.Combine(this._rootPath, nativePath);
+        string fullPath = Path.GetFullPath(combined);
+
+        if (!fullPath.StartsWith(this._rootPath, StringComparison.Ordinal))
+        {
+            throw new ArgumentException(
+                $"Invalid path: '{relativePath}'. The resolved path escapes the root directory.",
+                nameof(relativePath));
+        }
+
+        return fullPath;
+    }
+
+    /// <summary>
+    /// Resolves a relative directory path to a safe absolute path under the root directory.
+    /// An empty string resolves to the root directory itself.
+    /// </summary>
+    private string ResolveSafeDirectoryPath(string relativeDirectory)
+    {
+        if (string.IsNullOrEmpty(relativeDirectory))
+        {
+            return this._rootPath.TrimEnd(Path.DirectorySeparatorChar, Path.AltDirectorySeparatorChar);
+        }
+
+        return this.ResolveSafePath(relativeDirectory);
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/InMemoryAgentFileStore.cs

@@ -0,0 +1,160 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Text.RegularExpressions;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.FileSystemGlobbing;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An in-memory implementation of <see cref="AgentFileStore"/> that stores files in a dictionary.
+/// </summary>
+/// <remarks>
+/// This implementation is suitable for testing and lightweight scenarios where persistence is not required.
+/// Directory concepts are simulated using path prefixes — no explicit directory structure is maintained.
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class InMemoryAgentFileStore : AgentFileStore
+{
+    private readonly ConcurrentDictionary<string, string> _files = new(StringComparer.OrdinalIgnoreCase);
+
+    /// <inheritdoc />
+    public override Task WriteFileAsync(string path, string content, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        this._files[path] = content;
+        return Task.CompletedTask;
+    }
+
+    /// <inheritdoc />
+    public override Task<string?> ReadFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        this._files.TryGetValue(path, out string? content);
+        return Task.FromResult(content);
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> DeleteFileAsync(string path, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        return Task.FromResult(this._files.TryRemove(path, out _));
+    }
+
+    /// <inheritdoc />
+    public override Task<IReadOnlyList<string>> ListFilesAsync(string directory, CancellationToken cancellationToken = default)
+    {
+        string prefix = StorePaths.NormalizeRelativePath(directory, isDirectory: true);
+        if (prefix.Length > 0 && !prefix.EndsWith("/", StringComparison.Ordinal))
+        {
+            prefix += "/";
+        }
+
+        var files = this._files.Keys
+            .Where(k => k.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            .Select(k => k.Substring(prefix.Length))
+            .Where(k => k.IndexOf("/", StringComparison.Ordinal) < 0)
+            .ToList();
+
+        return Task.FromResult<IReadOnlyList<string>>(files);
+    }
+
+    /// <inheritdoc />
+    public override Task<bool> FileExistsAsync(string path, CancellationToken cancellationToken = default)
+    {
+        path = StorePaths.NormalizeRelativePath(path);
+        return Task.FromResult(this._files.ContainsKey(path));
+    }
+
+    /// <inheritdoc />
+    public override Task<IReadOnlyList<FileSearchResult>> SearchFilesAsync(string directory, string regexPattern, string? filePattern = null, CancellationToken cancellationToken = default)
+    {
+        // Normalize the directory prefix for path matching.
+        string prefix = StorePaths.NormalizeRelativePath(directory, isDirectory: true);
+        if (prefix.Length > 0 && !prefix.EndsWith("/", StringComparison.Ordinal))
+        {
+            prefix += "/";
+        }
+
+        // Compile the regex with a timeout to guard against catastrophic backtracking (ReDoS).
+        var regex = new Regex(regexPattern, RegexOptions.IgnoreCase, TimeSpan.FromSeconds(5));
+        Matcher? matcher = filePattern is not null ? StorePaths.CreateGlobMatcher(filePattern) : null;
+        var results = new List<FileSearchResult>();
+
+        foreach (var kvp in this._files)
+        {
+            // Only consider files within the target directory (by path prefix).
+            if (!kvp.Key.StartsWith(prefix, StringComparison.OrdinalIgnoreCase))
+            {
+                continue;
+            }
+
+            // Exclude files in subdirectories (direct children only).
+            string relativeName = kvp.Key.Substring(prefix.Length);
+            if (relativeName.IndexOf("/", StringComparison.Ordinal) >= 0)
+            {
+                continue;
+            }
+
+            // Apply the optional glob filter on the file name.
+            if (!StorePaths.MatchesGlob(relativeName, matcher))
+            {
+                continue;
+            }
+
+            // Search each line for regex matches, tracking line numbers and building a snippet.
+            string fileContent = kvp.Value;
+            string[] lines = fileContent.Split('\n');
+            var matchingLines = new List<FileSearchMatch>();
+            string? firstSnippet = null;
+            int lineStartOffset = 0;
+
+            for (int i = 0; i < lines.Length; i++)
+            {
+                Match match = regex.Match(lines[i]);
+                if (match.Success)
+                {
+                    matchingLines.Add(new FileSearchMatch { LineNumber = i + 1, Line = lines[i].TrimEnd('\r') });
+
+                    // Build a context snippet around the first match (±50 chars).
+                    if (firstSnippet is null)
+                    {
+                        int charIndex = lineStartOffset + match.Index;
+                        int snippetStart = Math.Max(0, charIndex - 50);
+                        int snippetEnd = Math.Min(fileContent.Length, charIndex + match.Value.Length + 50);
+                        firstSnippet = fileContent.Substring(snippetStart, snippetEnd - snippetStart);
+                    }
+                }
+
+                // Advance the offset past this line (including the '\n' separator).
+                lineStartOffset += lines[i].Length + 1;
+            }
+
+            if (matchingLines.Count > 0)
+            {
+                results.Add(new FileSearchResult
+                {
+                    FileName = relativeName,
+                    Snippet = firstSnippet!,
+                    MatchingLines = matchingLines,
+                });
+            }
+        }
+
+        return Task.FromResult<IReadOnlyList<FileSearchResult>>(results);
+    }
+
+    /// <inheritdoc />
+    public override Task CreateDirectoryAsync(string path, CancellationToken cancellationToken = default)
+    {
+        // No-op: directories are implicit from file paths in the in-memory store.
+        return Task.CompletedTask;
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/FileStore/StorePaths.cs

@@ -0,0 +1,119 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using Microsoft.Extensions.FileSystemGlobbing;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Internal helper for normalizing and validating relative store paths and matching glob patterns.
+/// Shared across <see cref="AgentFileStore"/> implementations and <see cref="FileMemoryProvider"/>.
+/// </summary>
+internal static class StorePaths
+{
+    /// <summary>
+    /// Normalizes a relative path by replacing backslashes with forward slashes, trimming leading
+    /// and trailing separators, and collapsing consecutive separators. Also validates that the path
+    /// does not contain rooted paths, drive roots, or <c>.</c>/<c>..</c> traversal segments.
+    /// </summary>
+    /// <param name="path">The relative path to normalize.</param>
+    /// <param name="isDirectory">
+    /// When <see langword="true"/>, the path represents a directory and an empty result (meaning root) is allowed.
+    /// When <see langword="false"/> (default), the path represents a file and an empty result is rejected.
+    /// </param>
+    /// <returns>The normalized forward-slash path.</returns>
+    /// <exception cref="ArgumentException">
+    /// Thrown when <paramref name="path"/> is rooted, starts with a drive letter, contains
+    /// <c>.</c> or <c>..</c> segments, or is empty when <paramref name="isDirectory"/> is <see langword="false"/>.
+    /// </exception>
+    internal static string NormalizeRelativePath(string path, bool isDirectory = false)
+    {
+        if (string.IsNullOrWhiteSpace(path))
+        {
+            if (!isDirectory)
+            {
+                throw new ArgumentException("A file path must not be empty or whitespace-only.", nameof(path));
+            }
+
+            return string.Empty;
+        }
+
+        string normalized = path.Replace('\\', '/').Trim('/');
+
+        if (Path.IsPathRooted(path) ||
+            path.StartsWith("/", StringComparison.Ordinal) ||
+            path.StartsWith("\\", StringComparison.Ordinal) ||
+            (normalized.Length >= 2 && char.IsLetter(normalized[0]) && normalized[1] == ':'))
+        {
+            throw new ArgumentException(
+                $"Invalid path: '{path}'. Paths must be relative and must not start with '/', '\\', or a drive root.",
+                nameof(path));
+        }
+
+        // Split, validate segments, and filter out empty segments to collapse consecutive separators.
+        string[] segments = normalized.Split('/');
+        var cleanSegments = new List<string>(segments.Length);
+        foreach (string segment in segments)
+        {
+            if (segment.Length == 0)
+            {
+                continue;
+            }
+
+            if (segment.Equals(".", StringComparison.Ordinal) || segment.Equals("..", StringComparison.Ordinal))
+            {
+                throw new ArgumentException(
+                    $"Invalid path: '{path}'. Paths must not contain '.' or '..' segments.",
+                    nameof(path));
+            }
+
+            cleanSegments.Add(segment);
+        }
+
+        string result = string.Join("/", cleanSegments);
+
+        if (!isDirectory && result.Length == 0)
+        {
+            throw new ArgumentException("A file path must not be empty.", nameof(path));
+        }
+
+        return result;
+    }
+
+    /// <summary>
+    /// Creates a <see cref="Matcher"/> for the specified glob pattern. Use the returned instance
+    /// to test multiple file names without allocating a new matcher for each one.
+    /// </summary>
+    /// <param name="filePattern">
+    /// The glob pattern to match against (e.g., <c>"*.md"</c>, <c>"research*"</c>).
+    /// </param>
+    /// <returns>A <see cref="Matcher"/> configured with the specified pattern.</returns>
+    internal static Matcher CreateGlobMatcher(string filePattern)
+    {
+        var matcher = new Matcher(StringComparison.OrdinalIgnoreCase);
+        matcher.AddInclude(filePattern);
+        return matcher;
+    }
+
+    /// <summary>
+    /// Determines whether a file name matches a pre-built glob <see cref="Matcher"/>.
+    /// </summary>
+    /// <param name="fileName">The file name to test (not a full path — just the name).</param>
+    /// <param name="matcher">
+    /// A pre-built <see cref="Matcher"/> to test against.
+    /// When <see langword="null"/>, this method returns <see langword="true"/> for any file name.
+    /// </param>
+    /// <returns><see langword="true"/> if the file name matches the pattern or if the matcher is <see langword="null"/>; otherwise, <see langword="false"/>.</returns>
+    internal static bool MatchesGlob(string fileName, Matcher? matcher)
+    {
+        if (matcher is null)
+        {
+            return true;
+        }
+
+        PatternMatchingResult result = matcher.Match(fileName);
+        return result.HasMatches;
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/SubAgents/SubAgentRuntimeState.cs

@@ -0,0 +1,32 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Holds non-serializable runtime references for in-flight sub-tasks within a single parent session.
+/// </summary>
+/// <remarks>
+/// Properties are marked with <see cref="JsonIgnoreAttribute"/> because <see cref="Task{TResult}"/>
+/// and <see cref="AgentSession"/> are not JSON-serializable. After deserialization (e.g., after a restart),
+/// a fresh empty instance is created and any previously-running tasks are marked as
+/// <see cref="SubTaskStatus.Lost"/> by <see cref="SubAgentsProvider"/>.
+/// </remarks>
+internal sealed class SubAgentRuntimeState
+{
+    /// <summary>
+    /// Gets the mapping of task IDs to their in-flight <see cref="Task{AgentResponse}"/> instances.
+    /// </summary>
+    [JsonIgnore]
+    public Dictionary<int, Task<AgentResponse>> InFlightTasks { get; } = [];
+
+    /// <summary>
+    /// Gets the mapping of task IDs to their sub-agent <see cref="AgentSession"/> instances,
+    /// needed for <c>ContinueTask</c>.
+    /// </summary>
+    [JsonIgnore]
+    public Dictionary<int, AgentSession> SubTaskSessions { get; } = [];
+}

dotnet/src/Microsoft.Agents.AI/Harness/SubAgents/SubAgentState.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the serializable state of sub-tasks managed by the <see cref="SubAgentsProvider"/>,
+/// stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class SubAgentState
+{
+    /// <summary>
+    /// Gets or sets the next ID to assign to a new sub-task.
+    /// </summary>
+    [JsonPropertyName("nextTaskId")]
+    public int NextTaskId { get; set; } = 1;
+
+    /// <summary>
+    /// Gets the list of sub-task metadata entries.
+    /// </summary>
+    [JsonPropertyName("tasks")]
+    public List<SubTaskInfo> Tasks { get; set; } = [];
+}

dotnet/src/Microsoft.Agents.AI/Harness/SubAgents/SubAgentsProvider.cs

@@ -0,0 +1,458 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.ComponentModel;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Text;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that enables an agent to delegate work to sub-agents asynchronously.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="SubAgentsProvider"/> allows a parent agent to start sub-tasks on child agents,
+/// wait for their completion, and retrieve results. Each sub-task runs in its own session and
+/// executes concurrently.
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>SubAgents_StartTask</c> — Start a sub-task on a named agent with text input. Returns the task ID.</description></item>
+/// <item><description><c>SubAgents_WaitForFirstCompletion</c> — Block until the first of the specified tasks completes. Returns the completed task's ID.</description></item>
+/// <item><description><c>SubAgents_GetTaskResults</c> — Retrieve the text output of a completed sub-task.</description></item>
+/// <item><description><c>SubAgents_GetAllTasks</c> — List all sub-tasks with their IDs, statuses, descriptions, and agent names.</description></item>
+/// <item><description><c>SubAgents_ContinueTask</c> — Send follow-up input to a completed sub-task's session to resume work.</description></item>
+/// <item><description><c>SubAgents_ClearCompletedTask</c> — Remove a completed sub-task and release its session to free memory.</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class SubAgentsProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## SubAgents
+        You have access to sub-agents that can perform work on your behalf.
+
+        - Use the `SubAgents_*` list of tools to start tasks on sub agents and check their results.
+        - Creating a sub task does not block, and sub-tasks run concurrently.
+        - Important: Always wait for outstanding tasks to finish before you finish processing.
+        - Important: After retrieving results from a completed task, clear it with SubAgents_ClearCompletedTask to free memory, unless you plan to continue it with SubAgents_ContinueTask.
+
+        {sub_agents}
+        """;
+
+    private readonly Dictionary<string, AIAgent> _agents;
+    private readonly ProviderSessionState<SubAgentState> _sessionState;
+    private readonly ProviderSessionState<SubAgentRuntimeState> _runtimeSessionState;
+    private readonly string _instructions;
+    private IReadOnlyList<string>? _stateKeys;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="SubAgentsProvider"/> class.
+    /// </summary>
+    /// <param name="agents">The collection of sub-agents available for delegation.</param>
+    /// <param name="options">Optional settings controlling the provider behavior.</param>
+    /// <exception cref="ArgumentNullException"><paramref name="agents"/> is <see langword="null"/>.</exception>
+    /// <exception cref="ArgumentException">An agent has a null or empty name, or agent names are not unique.</exception>
+    public SubAgentsProvider(IEnumerable<AIAgent> agents, SubAgentsProviderOptions? options = null)
+    {
+        _ = Throw.IfNull(agents);
+
+        this._agents = ValidateAndBuildAgentDictionary(agents);
+
+        string baseInstructions = options?.Instructions ?? DefaultInstructions;
+        string agentListText = options?.AgentListBuilder is not null
+            ? options.AgentListBuilder(this._agents)
+            : BuildDefaultAgentListText(this._agents);
+        this._instructions = baseInstructions.Replace("{sub_agents}", agentListText);
+
+        this._sessionState = new ProviderSessionState<SubAgentState>(
+            _ => new SubAgentState(),
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+
+        this._runtimeSessionState = new ProviderSessionState<SubAgentRuntimeState>(
+            _ => new SubAgentRuntimeState(),
+            this.GetType().Name + "_Runtime",
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey, this._runtimeSessionState.StateKey];
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        SubAgentState state = this._sessionState.GetOrInitializeState(context.Session);
+        SubAgentRuntimeState runtimeState = this._runtimeSessionState.GetOrInitializeState(context.Session);
+
+        return new ValueTask<AIContext>(new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this.CreateTools(state, runtimeState, context.Session),
+        });
+    }
+
+    /// <summary>
+    /// Validates the agent collection and builds a case-insensitive name dictionary.
+    /// </summary>
+    private static Dictionary<string, AIAgent> ValidateAndBuildAgentDictionary(IEnumerable<AIAgent> agents)
+    {
+        var dict = new Dictionary<string, AIAgent>(StringComparer.OrdinalIgnoreCase);
+        foreach (AIAgent agent in agents)
+        {
+            if (string.IsNullOrWhiteSpace(agent.Name))
+            {
+                throw new ArgumentException("All sub-agents must have a non-empty Name.", nameof(agents));
+            }
+
+            if (dict.ContainsKey(agent.Name))
+            {
+                throw new ArgumentException($"Duplicate sub-agent name: '{agent.Name}'. Agent names must be unique (case-insensitive).", nameof(agents));
+            }
+
+            dict[agent.Name] = agent;
+        }
+
+        if (dict.Count == 0)
+        {
+            throw new ArgumentException("At least one sub-agent must be provided.", nameof(agents));
+        }
+
+        return dict;
+    }
+
+    /// <summary>
+    /// Builds the default text listing available sub-agents and their descriptions.
+    /// </summary>
+    private static string BuildDefaultAgentListText(IReadOnlyDictionary<string, AIAgent> agents)
+    {
+        var sb = new StringBuilder();
+        sb.AppendLine("Available sub-agents:");
+        foreach (var kvp in agents)
+        {
+            sb.Append("- ").Append(kvp.Key);
+            if (!string.IsNullOrWhiteSpace(kvp.Value.Description))
+            {
+                sb.Append(": ").Append(kvp.Value.Description);
+            }
+
+            sb.AppendLine();
+        }
+
+        return sb.ToString();
+    }
+
+    /// <summary>
+    /// Refreshes the status of in-flight tasks in the given state for the specified session.
+    /// </summary>
+    private void TryRefreshTaskState(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    {
+        bool changed = false;
+        foreach (SubTaskInfo task in state.Tasks)
+        {
+            if (task.Status != SubTaskStatus.Running)
+            {
+                continue;
+            }
+
+            if (!runtimeState.InFlightTasks.TryGetValue(task.Id, out Task<AgentResponse>? inFlight))
+            {
+                // In-flight reference lost (e.g., after restart/deserialization).
+                task.Status = SubTaskStatus.Lost;
+                changed = true;
+                continue;
+            }
+
+            if (inFlight.IsCompleted)
+            {
+                FinalizeTask(task, inFlight, runtimeState);
+                changed = true;
+            }
+        }
+
+        if (changed)
+        {
+            this._sessionState.SaveState(session, state);
+        }
+    }
+
+    /// <summary>
+    /// Finalizes a task by extracting results from the completed Task and updating the SubTaskInfo.
+    /// </summary>
+    private static void FinalizeTask(SubTaskInfo taskInfo, Task<AgentResponse> completedTask, SubAgentRuntimeState runtimeState)
+    {
+        if (completedTask.Status == TaskStatus.RanToCompletion)
+        {
+            taskInfo.Status = SubTaskStatus.Completed;
+#pragma warning disable VSTHRD002 // Avoid problematic synchronous waits — task is already completed
+            taskInfo.ResultText = completedTask.Result.Text;
+#pragma warning restore VSTHRD002
+        }
+        else if (completedTask.IsFaulted)
+        {
+            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.ErrorText = completedTask.Exception?.InnerException?.Message ?? completedTask.Exception?.Message ?? "Unknown error";
+        }
+        else if (completedTask.IsCanceled)
+        {
+            taskInfo.Status = SubTaskStatus.Failed;
+            taskInfo.ErrorText = "Task was canceled.";
+        }
+
+        runtimeState.InFlightTasks.Remove(taskInfo.Id);
+    }
+
+    private AITool[] CreateTools(SubAgentState state, SubAgentRuntimeState runtimeState, AgentSession? session)
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(
+                async (
+                    [Description("The name of the sub agent to delegate the task to.")] string agentName,
+                    [Description("The request to pass to the sub agent.")] string input,
+                    [Description("A description of the task used to identify the task later.")] string description) =>
+                {
+                    if (!this._agents.TryGetValue(agentName, out AIAgent? agent))
+                    {
+                        return $"Error: No sub-agent found with name '{agentName}'. Available agents: {string.Join(", ", this._agents.Keys)}";
+                    }
+
+                    int taskId = state.NextTaskId++;
+                    var taskInfo = new SubTaskInfo
+                    {
+                        Id = taskId,
+                        AgentName = agentName,
+                        Description = description,
+                        Status = SubTaskStatus.Running,
+                    };
+                    state.Tasks.Add(taskInfo);
+
+                    // Create a dedicated session for this sub-task so it can be continued later.
+                    AgentSession subSession = await agent.CreateSessionAsync().ConfigureAwait(false);
+
+                    // Wrap in Task.Run to fork the ExecutionContext. AIAgent.RunAsync is a non-async
+                    // method that synchronously sets the static AsyncLocal CurrentRunContext. Without
+                    // this isolation, the sub-agent's RunAsync would overwrite the outer (calling)
+                    // agent's CurrentRunContext, corrupting all subsequent tool invocations in the
+                    // same FICC batch.
+                    runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(input, subSession));
+                    runtimeState.SubTaskSessions[taskId] = subSession;
+
+                    this._sessionState.SaveState(session, state);
+                    return $"Sub-task {taskId} started on agent '{agentName}'.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_StartTask",
+                    Description = "Start a sub-task on a named sub-agent. Returns a confirmation message containing the task ID.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                async (List<int> taskIds) =>
+                {
+                    if (taskIds.Count == 0)
+                    {
+                        return "Error: No task IDs provided.";
+                    }
+
+                    // Collect in-flight tasks matching the requested IDs (including already-completed ones,
+                    // since Task.WhenAny returns immediately for completed tasks).
+                    var waitableTasks = new List<(int Id, Task<AgentResponse> Task)>();
+                    foreach (int id in taskIds)
+                    {
+                        if (runtimeState.InFlightTasks.TryGetValue(id, out Task<AgentResponse>? inFlight))
+                        {
+                            waitableTasks.Add((id, inFlight));
+                        }
+                    }
+
+                    if (waitableTasks.Count == 0)
+                    {
+                        // Refresh state to catch any that completed.
+                        this.TryRefreshTaskState(state, runtimeState, session);
+                        this._sessionState.SaveState(session, state);
+
+                        // Check if any of the requested IDs are already complete.
+                        SubTaskInfo? alreadyComplete = state.Tasks.FirstOrDefault(t => taskIds.Contains(t.Id) && t.Status != SubTaskStatus.Running);
+                        if (alreadyComplete is not null)
+                        {
+                            return $"Task {alreadyComplete.Id} is not running; current status: {alreadyComplete.Status}.";
+                        }
+
+                        return "Error: None of the specified task IDs correspond to running tasks.";
+                    }
+
+                    // Wait for the first one to complete.
+                    Task completedTask = await Task.WhenAny(waitableTasks.Select(t => t.Task)).ConfigureAwait(false);
+
+                    // Find which ID completed.
+                    var completedEntry = waitableTasks.First(t => t.Task == completedTask);
+
+                    // Finalize the completed task.
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == completedEntry.Id);
+                    if (taskInfo is not null)
+                    {
+                        FinalizeTask(taskInfo, completedEntry.Task, runtimeState);
+                        this._sessionState.SaveState(session, state);
+                    }
+
+                    return $"Task {completedEntry.Id} finished with status: {taskInfo?.Status.ToString() ?? "Unknown"}.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_WaitForFirstCompletion",
+                    Description = "Block until the first of the specified sub-tasks completes. Provide one or more task IDs. Returns a status message containing the ID of the task that completed first.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (int taskId) =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    if (taskInfo is null)
+                    {
+                        return $"Error: No task found with ID {taskId}.";
+                    }
+
+                    return taskInfo.Status switch
+                    {
+                        SubTaskStatus.Completed => taskInfo.ResultText ?? "(no output)",
+                        SubTaskStatus.Failed => $"Task failed: {taskInfo.ErrorText ?? "Unknown error"}",
+                        SubTaskStatus.Lost => "Task state was lost (reference unavailable).",
+                        SubTaskStatus.Running => $"Task {taskId} is still running.",
+                        _ => $"Task {taskId} has status: {taskInfo.Status}.",
+                    };
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_GetTaskResults",
+                    Description = "Get the text output of a sub-task by its ID. Returns the result text if complete, or status information if still running or failed.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    if (state.Tasks.Count == 0)
+                    {
+                        return "No tasks.";
+                    }
+
+                    var sb = new StringBuilder();
+                    sb.AppendLine("Tasks:");
+                    foreach (SubTaskInfo task in state.Tasks)
+                    {
+                        sb.Append("- Task ").Append(task.Id).Append(" [").Append(task.Status).Append("] (").Append(task.AgentName).Append("): ").AppendLine(task.Description);
+                    }
+
+                    return sb.ToString();
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_GetAllTasks",
+                    Description = "List all sub-tasks with their IDs, statuses, agent names, and descriptions.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (int taskId, string text) =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    if (taskInfo is null)
+                    {
+                        return $"Error: No task found with ID {taskId}.";
+                    }
+
+                    if (taskInfo.Status == SubTaskStatus.Lost)
+                    {
+                        return $"Error: Task {taskId} cannot be continued because its session was lost (e.g., after a session restore). Start a new task instead.";
+                    }
+
+                    if (taskInfo.Status == SubTaskStatus.Running)
+                    {
+                        return $"Error: Task {taskId} is still running. Wait for it to complete before continuing.";
+                    }
+
+                    if (!this._agents.TryGetValue(taskInfo.AgentName, out AIAgent? agent))
+                    {
+                        return $"Error: Agent '{taskInfo.AgentName}' is no longer available.";
+                    }
+
+                    if (!runtimeState.SubTaskSessions.TryGetValue(taskId, out AgentSession? subSession))
+                    {
+                        return $"Error: Session for task {taskId} is no longer available.";
+                    }
+
+                    // Reset task state and start a new run on the existing session.
+                    taskInfo.Status = SubTaskStatus.Running;
+                    taskInfo.ResultText = null;
+                    taskInfo.ErrorText = null;
+
+                    // Wrap in Task.Run to isolate the ExecutionContext (see StartSubTask comment).
+                    runtimeState.InFlightTasks[taskId] = Task.Run(() => agent.RunAsync(text, subSession));
+
+                    this._sessionState.SaveState(session, state);
+                    return $"Task {taskId} continued with new input.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_ContinueTask",
+                    Description = "Send follow-up input to a completed or failed sub-task to resume its work. The sub-task's session is preserved, so the agent retains conversational context.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (int taskId) =>
+                {
+                    this.TryRefreshTaskState(state, runtimeState, session);
+
+                    SubTaskInfo? taskInfo = state.Tasks.FirstOrDefault(t => t.Id == taskId);
+                    if (taskInfo is null)
+                    {
+                        return $"Error: No task found with ID {taskId}.";
+                    }
+
+                    if (taskInfo.Status == SubTaskStatus.Running)
+                    {
+                        return $"Error: Task {taskId} is still running. Wait for it to complete before clearing.";
+                    }
+
+                    // Remove the task from state.
+                    state.Tasks.Remove(taskInfo);
+
+                    // Clean up runtime references.
+                    runtimeState.InFlightTasks.Remove(taskId);
+                    runtimeState.SubTaskSessions.Remove(taskId);
+
+                    this._sessionState.SaveState(session, state);
+                    return $"Task {taskId} cleared.";
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "SubAgents_ClearCompletedTask",
+                    Description = "Remove a completed or failed sub-task and release its session to free memory. Use this after retrieving results when you no longer need to continue the task.",
+                    SerializerOptions = serializerOptions,
+                }),
+        ];
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/SubAgents/SubAgentsProviderOptions.cs

@@ -0,0 +1,39 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="SubAgentsProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class SubAgentsProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the sub-agent tools.
+    /// </summary>
+    /// <remarks>
+    /// Use the <c>{sub_agents}</c> placeholder to allow the provider to inject
+    /// the formatted list of available sub agents.
+    /// </remarks>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to use the sub-agent tools.
+    /// The agent list is always appended after the instructions regardless of this setting.
+    /// </value>
+    public string? Instructions { get; set; }
+
+    /// <summary>
+    /// Gets or sets a custom function that builds the agent list text to append to instructions.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider generates a standard list of agent names and descriptions.
+    /// When set, this function receives the dictionary of available agents (keyed by name) and should return
+    /// a formatted string describing the available sub-agents.
+    /// </value>
+    public Func<IReadOnlyDictionary<string, AIAgent>, string>? AgentListBuilder { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/SubAgents/SubTaskInfo.cs

@@ -0,0 +1,50 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the metadata and result of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class SubTaskInfo
+{
+    /// <summary>
+    /// Gets or sets the unique identifier for this sub-task.
+    /// </summary>
+    [JsonPropertyName("id")]
+    public int Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the name of the agent that is executing this sub-task.
+    /// </summary>
+    [JsonPropertyName("agentName")]
+    public string AgentName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets a description of what this sub-task is doing.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string Description { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the current status of this sub-task.
+    /// </summary>
+    [JsonPropertyName("status")]
+    public SubTaskStatus Status { get; set; }
+
+    /// <summary>
+    /// Gets or sets the text result of the sub-task, populated when the task completes successfully.
+    /// </summary>
+    [JsonPropertyName("resultText")]
+    public string? ResultText { get; set; }
+
+    /// <summary>
+    /// Gets or sets the error message if the sub-task failed.
+    /// </summary>
+    [JsonPropertyName("errorText")]
+    public string? ErrorText { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/SubAgents/SubTaskStatus.cs

@@ -0,0 +1,34 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the status of a sub-task managed by the <see cref="SubAgentsProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public enum SubTaskStatus
+{
+    /// <summary>
+    /// The sub-task is currently running.
+    /// </summary>
+    Running,
+
+    /// <summary>
+    /// The sub-task completed successfully.
+    /// </summary>
+    Completed,
+
+    /// <summary>
+    /// The sub-task failed with an error.
+    /// </summary>
+    Failed,
+
+    /// <summary>
+    /// The sub-task's in-flight reference was lost (e.g., after a restart),
+    /// and its final state cannot be determined.
+    /// </summary>
+    Lost,
+}

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoItem.cs

@@ -0,0 +1,38 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a single todo item managed by the <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class TodoItem
+{
+    /// <summary>
+    /// Gets or sets the unique identifier for this todo item.
+    /// </summary>
+    [JsonPropertyName("id")]
+    public int Id { get; set; }
+
+    /// <summary>
+    /// Gets or sets the title of this todo item.
+    /// </summary>
+    [JsonPropertyName("title")]
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets an optional description providing additional details about this todo item.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string? Description { get; set; }
+
+    /// <summary>
+    /// Gets or sets a value indicating whether this todo item has been completed.
+    /// </summary>
+    [JsonPropertyName("isComplete")]
+    public bool IsComplete { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoItemInput.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the input for creating a new todo item via the <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class TodoItemInput
+{
+    /// <summary>
+    /// Gets or sets the title of the todo item to create.
+    /// </summary>
+    [JsonPropertyName("title")]
+    public string Title { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets an optional description providing additional details about the todo item.
+    /// </summary>
+    [JsonPropertyName("description")]
+    public string? Description { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoProvider.cs

@@ -0,0 +1,209 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// An <see cref="AIContextProvider"/> that provides todo management tools and instructions
+/// to an agent for tracking work items during long-running complex tasks.
+/// </summary>
+/// <remarks>
+/// <para>
+/// The <see cref="TodoProvider"/> enables agents to create, complete, remove, and query todo items
+/// as part of their planning and execution workflow. Todo state is stored in the session's
+/// <see cref="AgentSessionStateBag"/> and persists across agent invocations within the same session.
+/// </para>
+/// <para>
+/// This provider exposes the following tools to the agent:
+/// <list type="bullet">
+/// <item><description><c>TodoList_Add</c> — Add one or more todo items, each with a title and optional description.</description></item>
+/// <item><description><c>TodoList_Complete</c> — Mark one or more todo items as complete by their IDs.</description></item>
+/// <item><description><c>TodoList_Remove</c> — Remove one or more todo items by their IDs.</description></item>
+/// <item><description><c>TodoList_GetRemaining</c> — Retrieve only incomplete todo items.</description></item>
+/// <item><description><c>TodoList_GetAll</c> — Retrieve all todo items (complete and incomplete).</description></item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class TodoProvider : AIContextProvider
+{
+    private const string DefaultInstructions =
+        """
+        ## Todo Items
+
+        You have access to a todo list for tracking work items.
+        While planning, make sure that you break down complex tasks into manageable todo items and add them to the list.
+        Ask questions from the user where clarification is needed to create effective todos.
+        If the user provides feedback on your plan, adjust your todos accordingly by adding new items or removing irrelevant ones.
+        During execution, use the todo list to keep track of what needs to be done, mark items as complete when finished, and remove any items that are no longer needed.
+        When a user changes the topic or changes their mind, ensure that you update the todo list accordingly by removing irrelevant items or adding new ones as needed.
+        
+        Use these tools to manage your tasks:
+        - Use TodoList_Add to break down complex work into trackable items (supports adding one or many at once).
+        - Use TodoList_Complete to mark items as done when finished (supports one or many at once).
+        - Use TodoList_GetRemaining to check what work is still pending.
+        - Use TodoList_GetAll to review the full list including completed items.
+        - Use TodoList_Remove to remove items that are no longer needed (supports one or many at once).
+        """;
+
+    private readonly ProviderSessionState<TodoState> _sessionState;
+    private readonly string _instructions;
+    private IReadOnlyList<string>? _stateKeys;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="TodoProvider"/> class.
+    /// </summary>
+    /// <param name="options">Optional settings that control provider behavior. When <see langword="null"/>, defaults are used.</param>
+    public TodoProvider(TodoProviderOptions? options = null)
+    {
+        this._instructions = options?.Instructions ?? DefaultInstructions;
+        this._sessionState = new ProviderSessionState<TodoState>(
+            _ => new TodoState(),
+            this.GetType().Name,
+            AgentJsonUtilities.DefaultOptions);
+    }
+
+    /// <inheritdoc />
+    public override IReadOnlyList<string> StateKeys => this._stateKeys ??= [this._sessionState.StateKey];
+
+    /// <summary>
+    /// Gets all todo items from the session state.
+    /// </summary>
+    /// <param name="session">The agent session to read todos from.</param>
+    /// <returns>A read-only list of all todo items.</returns>
+    public IReadOnlyList<TodoItem> GetAllTodos(AgentSession? session)
+    {
+        return this._sessionState.GetOrInitializeState(session).Items;
+    }
+
+    /// <summary>
+    /// Gets the remaining (incomplete) todo items from the session state.
+    /// </summary>
+    /// <param name="session">The agent session to read todos from.</param>
+    /// <returns>A list of incomplete todo items.</returns>
+    public List<TodoItem> GetRemainingTodos(AgentSession? session)
+    {
+        return this._sessionState.GetOrInitializeState(session).Items.Where(t => !t.IsComplete).ToList();
+    }
+
+    /// <inheritdoc />
+    protected override ValueTask<AIContext> ProvideAIContextAsync(InvokingContext context, CancellationToken cancellationToken = default)
+    {
+        TodoState state = this._sessionState.GetOrInitializeState(context.Session);
+
+        return new ValueTask<AIContext>(new AIContext
+        {
+            Instructions = this._instructions,
+            Tools = this.CreateTools(state, context.Session),
+        });
+    }
+
+    // Note: These tool delegates mutate shared session state without synchronization.
+    // This is safe because FunctionInvokingChatClient serializes tool calls within a single run.
+    private AITool[] CreateTools(TodoState state, AgentSession? session)
+    {
+        var serializerOptions = AgentJsonUtilities.DefaultOptions;
+
+        return
+        [
+            AIFunctionFactory.Create(
+                (List<TodoItemInput> todos) =>
+                {
+                    var created = new List<TodoItem>();
+                    foreach (var input in todos)
+                    {
+                        var item = new TodoItem
+                        {
+                            Id = state.NextId++,
+                            Title = input.Title,
+                            Description = input.Description,
+                        };
+                        state.Items.Add(item);
+                        created.Add(item);
+                    }
+
+                    this._sessionState.SaveState(session, state);
+                    return created;
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_Add",
+                    Description = "Add one or more todo items. Each item has a title and an optional description. Returns the list of created todo items.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (List<int> ids) =>
+                {
+                    var idSet = new HashSet<int>(ids);
+                    int completed = 0;
+                    foreach (TodoItem item in state.Items)
+                    {
+                        if (!item.IsComplete && idSet.Contains(item.Id))
+                        {
+                            item.IsComplete = true;
+                            completed++;
+                        }
+                    }
+
+                    if (completed > 0)
+                    {
+                        this._sessionState.SaveState(session, state);
+                    }
+
+                    return completed;
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_Complete",
+                    Description = "Mark one or more todo items as complete by their IDs. Returns the number of items that were found and marked complete.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                (List<int> ids) =>
+                {
+                    var idSet = new HashSet<int>(ids);
+                    int removed = state.Items.RemoveAll(t => idSet.Contains(t.Id));
+
+                    if (removed > 0)
+                    {
+                        this._sessionState.SaveState(session, state);
+                    }
+
+                    return removed;
+                },
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_Remove",
+                    Description = "Remove one or more todo items by their IDs. Returns the number of items that were found and removed.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () => state.Items.Where(t => !t.IsComplete).ToList(),
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_GetRemaining",
+                    Description = "Retrieve the list of incomplete todo items.",
+                    SerializerOptions = serializerOptions,
+                }),
+
+            AIFunctionFactory.Create(
+                () => state.Items,
+                new AIFunctionFactoryOptions
+                {
+                    Name = "TodoList_GetAll",
+                    Description = "Retrieve the full list of todo items, both complete and incomplete.",
+                    SerializerOptions = serializerOptions,
+                }),
+        ];
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoProviderOptions.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Options controlling the behavior of <see cref="TodoProvider"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class TodoProviderOptions
+{
+    /// <summary>
+    /// Gets or sets custom instructions provided to the agent for using the todo tools.
+    /// </summary>
+    /// <value>
+    /// When <see langword="null"/> (the default), the provider uses built-in instructions
+    /// that guide the agent on how to manage todos effectively.
+    /// </value>
+    public string? Instructions { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/Todo/TodoState.cs

@@ -0,0 +1,28 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the state of the todo list managed by the <see cref="TodoProvider"/>,
+/// stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class TodoState
+{
+    /// <summary>
+    /// Gets the list of todo items.
+    /// </summary>
+    [JsonPropertyName("items")]
+    public List<TodoItem> Items { get; set; } = [];
+
+    /// <summary>
+    /// Gets or sets the next ID to assign to a new todo item.
+    /// </summary>
+    [JsonPropertyName("nextId")]
+    public int NextId { get; set; } = 1;
+}

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/AlwaysApproveToolApprovalResponseContent.cs

@@ -0,0 +1,67 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Wraps a <see cref="ToolApprovalResponseContent"/> with additional "always approve" settings,
+/// enabling the <see cref="ToolApprovalAgent"/> middleware to record standing approval rules
+/// so that future matching tool calls are auto-approved without user interaction.
+/// </summary>
+/// <remarks>
+/// <para>
+/// Instances of this class should not be created directly. Instead, use the extension methods
+/// <see cref="ToolApprovalRequestContentExtensions.CreateAlwaysApproveToolResponse"/> or
+/// <see cref="ToolApprovalRequestContentExtensions.CreateAlwaysApproveToolWithArgumentsResponse"/>
+/// on <see cref="ToolApprovalRequestContent"/> to create instances with the appropriate flags set.
+/// </para>
+/// <para>
+/// The <see cref="ToolApprovalAgent"/> middleware will unwrap the <see cref="InnerResponse"/> to forward
+/// to the inner agent, while extracting the approval settings to persist as <see cref="ToolApprovalRule"/>
+/// entries in the session state.
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class AlwaysApproveToolApprovalResponseContent : AIContent
+{
+    /// <summary>
+    /// Initializes a new instance of the <see cref="AlwaysApproveToolApprovalResponseContent"/> class.
+    /// </summary>
+    /// <param name="innerResponse">The underlying approval response to forward to the agent.</param>
+    /// <param name="alwaysApproveTool">
+    /// When <see langword="true"/>, all future calls to this tool type will be auto-approved.
+    /// </param>
+    /// <param name="alwaysApproveToolWithArguments">
+    /// When <see langword="true"/>, all future calls to this tool type with the same arguments will be auto-approved.
+    /// </param>
+    internal AlwaysApproveToolApprovalResponseContent(
+        ToolApprovalResponseContent innerResponse,
+        bool alwaysApproveTool,
+        bool alwaysApproveToolWithArguments)
+    {
+        this.InnerResponse = Throw.IfNull(innerResponse);
+        this.AlwaysApproveTool = alwaysApproveTool;
+        this.AlwaysApproveToolWithArguments = alwaysApproveToolWithArguments;
+    }
+
+    /// <summary>
+    /// Gets the underlying <see cref="ToolApprovalResponseContent"/> that will be forwarded to the inner agent.
+    /// </summary>
+    public ToolApprovalResponseContent InnerResponse { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether all future calls to the same tool should be auto-approved
+    /// regardless of the arguments provided.
+    /// </summary>
+    public bool AlwaysApproveTool { get; }
+
+    /// <summary>
+    /// Gets a value indicating whether all future calls to the same tool with the exact same
+    /// arguments should be auto-approved.
+    /// </summary>
+    public bool AlwaysApproveToolWithArguments { get; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalAgent.cs

@@ -0,0 +1,781 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Linq;
+using System.Runtime.CompilerServices;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// A <see cref="DelegatingAIAgent"/> middleware that implements "don't ask again" tool approval behavior
+/// and queues multiple approval requests to present them to the caller one at a time.
+/// </summary>
+/// <remarks>
+/// <para>
+/// This middleware intercepts the approval flow between the caller and the inner agent:
+/// </para>
+/// <list type="bullet">
+/// <item>
+/// <b>Outbound (response to caller):</b> When the inner agent surfaces <see cref="ToolApprovalRequestContent"/> items,
+/// the middleware checks whether matching <see cref="ToolApprovalRule"/> entries have been recorded. Matched requests
+/// are auto-approved and stored as collected approval responses. If multiple unapproved requests remain, only the
+/// first is returned to the caller while the rest are queued. On subsequent calls, queued items are re-evaluated
+/// against rules (which may have been updated by the caller's "always approve" response) and presented one at a time.
+/// Once all queued requests are resolved, the collected responses are injected and the inner agent is called again.
+/// </item>
+/// <item>
+/// <b>Inbound (caller to agent):</b> When the caller sends an <see cref="AlwaysApproveToolApprovalResponseContent"/>,
+/// the middleware extracts the standing approval settings, records them as <see cref="ToolApprovalRule"/> entries
+/// in the session state, and forwards only the unwrapped <see cref="ToolApprovalResponseContent"/> to the inner agent.
+/// Content ordering within each message is preserved.
+/// </item>
+/// </list>
+/// <para>
+/// Approval rules are persisted in the <see cref="AgentSessionStateBag"/> and survive across agent runs within the same session.
+/// Two categories of rules are supported:
+/// </para>
+/// <list type="bullet">
+/// <item><b>Tool-level:</b> Approve all calls to a specific tool, regardless of arguments.</item>
+/// <item><b>Tool+arguments:</b> Approve all calls to a specific tool with exactly matching arguments.</item>
+/// </list>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public sealed class ToolApprovalAgent : DelegatingAIAgent
+{
+    private readonly ProviderSessionState<ToolApprovalState> _sessionState;
+    private readonly JsonSerializerOptions _jsonSerializerOptions;
+
+    /// <summary>
+    /// Initializes a new instance of the <see cref="ToolApprovalAgent"/> class.
+    /// </summary>
+    /// <param name="innerAgent">The underlying agent to delegate to.</param>
+    /// <param name="jsonSerializerOptions">
+    /// Optional <see cref="JsonSerializerOptions"/> used for serializing argument values when storing rules
+    /// and for persisting state. When <see langword="null"/>, <see cref="AgentJsonUtilities.DefaultOptions"/> is used.
+    /// </param>
+    /// <exception cref="ArgumentNullException"><paramref name="innerAgent"/> is <see langword="null"/>.</exception>
+    public ToolApprovalAgent(AIAgent innerAgent, JsonSerializerOptions? jsonSerializerOptions = null)
+        : base(innerAgent)
+    {
+        this._jsonSerializerOptions = jsonSerializerOptions ?? AgentJsonUtilities.DefaultOptions;
+        this._sessionState = new ProviderSessionState<ToolApprovalState>(
+            _ => new ToolApprovalState(),
+            "toolApprovalState",
+            this._jsonSerializerOptions);
+    }
+
+    /// <inheritdoc />
+    protected override async Task<AgentResponse> RunCoreAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        // Steps 1–2: Unwrap AlwaysApprove wrappers, process any queued approval requests.
+        var (state, callerMessages, nextQueuedItem) = this.PrepareInboundMessages(messages, session);
+
+        if (nextQueuedItem is not null)
+        {
+            // Queue still has items — return the next one to the caller for approval.
+            return new AgentResponse(new ChatMessage(ChatRole.Assistant, [nextQueuedItem]));
+        }
+
+        // 3. Call the inner agent in a loop. If the inner agent returns approval requests
+        //    that are ALL auto-approved by standing rules, we immediately re-call with the
+        //    collected approval responses injected. This avoids returning empty responses.
+        while (true)
+        {
+            // Inject any collected approval responses as a user message ahead of the caller's messages.
+            var processedMessages = this.InjectCollectedResponses(callerMessages, state, session);
+
+            var response = await this.InnerAgent.RunAsync(processedMessages, session, options, cancellationToken).ConfigureAwait(false);
+
+            // Classify approval requests: auto-approve matching, queue excess, keep first unapproved.
+            bool allAutoApproved = this.ProcessAndQueueOutboundApprovalRequests(response.Messages, state, session);
+
+            if (!allAutoApproved)
+            {
+                // Response has real content or an unapproved approval request — return to caller.
+                return response;
+            }
+
+            // All approval requests were auto-approved. Loop to re-invoke with them injected.
+            callerMessages = [];
+        }
+    }
+
+    /// <inheritdoc />
+    protected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreStreamingAsync(
+        IEnumerable<ChatMessage> messages,
+        AgentSession? session = null,
+        AgentRunOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        // Steps 1–2: Unwrap AlwaysApprove wrappers, process any queued approval requests.
+        var (state, callerMessages, nextQueuedItem) = this.PrepareInboundMessages(messages, session);
+
+        if (nextQueuedItem is not null)
+        {
+            // Queue still has items — yield the next one to the caller for approval.
+            yield return new AgentResponseUpdate(ChatRole.Assistant, [nextQueuedItem]);
+            yield break;
+        }
+
+        // 3. Stream from the inner agent in a loop. If all approval requests from the stream
+        //    are auto-approved by standing rules, we immediately re-stream with the collected
+        //    approval responses injected. This avoids returning empty streams.
+        while (true)
+        {
+            // Inject any collected approval responses as a user message ahead of the caller's messages.
+            var processedMessages = this.InjectCollectedResponses(callerMessages, state, session);
+
+            // Stream from the inner agent. Non-approval content is yielded immediately.
+            // Approval requests are collected (not yielded) so we can classify the full batch.
+            List<ToolApprovalRequestContent> streamedApprovalRequests = [];
+
+            await foreach (var update in this.InnerAgent.RunStreamingAsync(processedMessages, session, options, cancellationToken).ConfigureAwait(false))
+            {
+                // Fast path: no approval content in this update — yield as-is.
+                bool hasApprovalRequests = false;
+                foreach (var content in update.Contents)
+                {
+                    if (content is ToolApprovalRequestContent)
+                    {
+                        hasApprovalRequests = true;
+                        break;
+                    }
+                }
+
+                if (!hasApprovalRequests)
+                {
+                    yield return update;
+                    continue;
+                }
+
+                // Split the update: collect approval requests, keep other content.
+                var filteredContents = new List<AIContent>();
+                foreach (var content in update.Contents)
+                {
+                    if (content is ToolApprovalRequestContent tarc)
+                    {
+                        streamedApprovalRequests.Add(tarc);
+                    }
+                    else
+                    {
+                        filteredContents.Add(content);
+                    }
+                }
+
+                // Yield the non-approval portion of the update (if any) as a cloned update.
+                if (filteredContents.Count > 0)
+                {
+                    yield return new AgentResponseUpdate(update.Role, filteredContents)
+                    {
+                        AuthorName = update.AuthorName,
+                        AdditionalProperties = update.AdditionalProperties,
+                        AgentId = update.AgentId,
+                        ResponseId = update.ResponseId,
+                        MessageId = update.MessageId,
+                        CreatedAt = update.CreatedAt,
+                        ContinuationToken = update.ContinuationToken,
+                        FinishReason = update.FinishReason,
+                        RawRepresentation = update.RawRepresentation,
+                    };
+                }
+            }
+
+            // If the stream contained no approval requests, we're done.
+            if (streamedApprovalRequests.Count == 0)
+            {
+                yield break;
+            }
+
+            // 4. Classify the collected approval requests against standing rules.
+            List<ToolApprovalRequestContent> unapproved = [];
+            foreach (var tarc in streamedApprovalRequests)
+            {
+                if (MatchesRule(tarc, state.Rules, this._jsonSerializerOptions))
+                {
+                    state.CollectedApprovalResponses.Add(
+                        tarc.CreateResponse(approved: true, reason: "Auto-approved by standing rule"));
+                }
+                else
+                {
+                    unapproved.Add(tarc);
+                }
+            }
+
+            // If all were auto-approved, loop to re-invoke the inner agent with them injected.
+            if (unapproved.Count == 0)
+            {
+                callerMessages = [];
+                continue;
+            }
+
+            // 5. Queue excess unapproved requests and yield only the first to the caller.
+            if (unapproved.Count > 1)
+            {
+                state.QueuedApprovalRequests.AddRange(unapproved.GetRange(1, unapproved.Count - 1));
+            }
+
+            this._sessionState.SaveState(session, state);
+            yield return new AgentResponseUpdate(ChatRole.Assistant, [unapproved[0]]);
+            yield break;
+        }
+    }
+
+    /// <summary>
+    /// Extracts <see cref="ToolApprovalResponseContent"/> instances from the caller's messages
+    /// and collects them into <see cref="ToolApprovalState.CollectedApprovalResponses"/>.
+    /// Extracted responses are removed from the messages in-place.
+    /// </summary>
+    private static void CollectApprovalResponsesFromMessages(
+        List<ChatMessage> messages,
+        ToolApprovalState state)
+    {
+        // Walk messages in reverse so we can safely remove by index.
+        for (int i = messages.Count - 1; i >= 0; i--)
+        {
+            var message = messages[i];
+
+            // Quick check: does this message contain any approval responses?
+            bool hasApprovalResponse = false;
+            foreach (var content in message.Contents)
+            {
+                if (content is ToolApprovalResponseContent)
+                {
+                    hasApprovalResponse = true;
+                    break;
+                }
+            }
+
+            if (!hasApprovalResponse)
+            {
+                continue;
+            }
+
+            // Separate approval responses (→ state) from other content (→ keep in message).
+            var remaining = new List<AIContent>(message.Contents.Count);
+            foreach (var content in message.Contents)
+            {
+                if (content is ToolApprovalResponseContent response)
+                {
+                    state.CollectedApprovalResponses.Add(response);
+                }
+                else
+                {
+                    remaining.Add(content);
+                }
+            }
+
+            // Remove the message entirely if it only contained approval responses,
+            // otherwise replace it with a clone that has the approval responses stripped.
+            if (remaining.Count == 0)
+            {
+                messages.RemoveAt(i);
+            }
+            else
+            {
+                var cloned = message.Clone();
+                cloned.Contents = remaining;
+                messages[i] = cloned;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Re-evaluates queued approval requests against current rules and auto-approves any that now match.
+    /// </summary>
+    private void DrainAutoApprovableFromQueue(ToolApprovalState state)
+    {
+        for (int i = state.QueuedApprovalRequests.Count - 1; i >= 0; i--)
+        {
+            if (MatchesRule(state.QueuedApprovalRequests[i], state.Rules, this._jsonSerializerOptions))
+            {
+                state.CollectedApprovalResponses.Add(
+                    state.QueuedApprovalRequests[i].CreateResponse(approved: true, reason: "Auto-approved by standing rule"));
+                state.QueuedApprovalRequests.RemoveAt(i);
+            }
+        }
+    }
+
+    /// <summary>
+    /// Performs the common inbound processing shared by both the streaming and non-streaming paths:
+    /// <list type="number">
+    /// <item>Unwraps <see cref="AlwaysApproveToolApprovalResponseContent"/> wrappers, extracting standing rules.</item>
+    /// <item>If there are queued approval requests from a previous batch, collects the caller's responses,
+    /// drains any items now resolvable by new rules, and dequeues the next item if any remain.</item>
+    /// </list>
+    /// </summary>
+    /// <returns>
+    /// A tuple of (state, processed caller messages, next queued item or <see langword="null"/> if the queue is resolved).
+    /// When the returned item is non-null, the caller should return/yield it without calling the inner agent.
+    /// </returns>
+    private (ToolApprovalState State, List<ChatMessage> CallerMessages, ToolApprovalRequestContent? NextQueuedItem)
+        PrepareInboundMessages(IEnumerable<ChatMessage> messages, AgentSession? session)
+    {
+        var state = this._sessionState.GetOrInitializeState(session);
+
+        // 1. Unwrap any AlwaysApprove wrappers in the caller's messages.
+        //    This extracts standing approval rules into state and replaces wrappers with plain responses.
+        var callerMessages = UnwrapAlwaysApproveResponses(messages, state, this._jsonSerializerOptions);
+
+        // 2. If there are queued approval requests from a previous batch, handle them
+        //    before calling the inner agent.
+        if (state.QueuedApprovalRequests.Count > 0)
+        {
+            // Collect the caller's approval/denial responses for the previously dequeued item
+            // and store them in state for the next downstream call.
+            CollectApprovalResponsesFromMessages(callerMessages, state);
+
+            // Re-evaluate remaining queued items — the caller may have added new rules
+            // (e.g., "always approve this tool") that resolve additional items.
+            this.DrainAutoApprovableFromQueue(state);
+
+            if (state.QueuedApprovalRequests.Count > 0)
+            {
+                // More items remain — dequeue the next one for the caller.
+                var next = state.QueuedApprovalRequests[0];
+                state.QueuedApprovalRequests.RemoveAt(0);
+                this._sessionState.SaveState(session, state);
+                return (state, callerMessages, next);
+            }
+
+            // Queue fully resolved — caller should proceed to call the inner agent.
+        }
+
+        return (state, callerMessages, null);
+    }
+
+    /// <summary>
+    /// Injects any collected approval responses as user messages before the caller's messages,
+    /// then clears the collected responses.
+    /// </summary>
+    private List<ChatMessage> InjectCollectedResponses(
+        List<ChatMessage> callerMessages,
+        ToolApprovalState state,
+        AgentSession? session)
+    {
+        if (state.CollectedApprovalResponses.Count > 0)
+        {
+            List<ChatMessage> result = [new ChatMessage(ChatRole.User, [.. state.CollectedApprovalResponses])];
+            result.AddRange(callerMessages);
+
+            state.CollectedApprovalResponses.Clear();
+            this._sessionState.SaveState(session, state);
+
+            return result;
+        }
+
+        return callerMessages;
+    }
+
+    /// <summary>
+    /// Processes outbound approval requests from non-streaming response messages.
+    /// Auto-approvable requests are collected as responses, and if multiple unapproved requests
+    /// remain, only the first is kept in the response while the rest are queued for subsequent calls.
+    /// </summary>
+    /// <returns>
+    /// <see langword="true"/> if all TARc items were auto-approved (caller should re-invoke the inner agent);
+    /// <see langword="false"/> otherwise.
+    /// </returns>
+    private bool ProcessAndQueueOutboundApprovalRequests(
+        IList<ChatMessage> responseMessages,
+        ToolApprovalState state,
+        AgentSession? session)
+    {
+        // Pass 1: Scan all response messages and classify each approval request as
+        //         auto-approved (matches a standing rule) or unapproved (needs caller decision).
+        var autoApproved = new List<ToolApprovalRequestContent>();
+        var unapproved = new List<ToolApprovalRequestContent>();
+
+        foreach (var message in responseMessages)
+        {
+            foreach (var content in message.Contents)
+            {
+                if (content is ToolApprovalRequestContent tarc)
+                {
+                    if (MatchesRule(tarc, state.Rules, this._jsonSerializerOptions))
+                    {
+                        autoApproved.Add(tarc);
+                    }
+                    else
+                    {
+                        unapproved.Add(tarc);
+                    }
+                }
+            }
+        }
+
+        // Nothing to process: no auto-approved items and at most one unapproved (no queueing needed).
+        if (autoApproved.Count == 0 && unapproved.Count <= 1)
+        {
+            return false;
+        }
+
+        // Store auto-approved responses for later injection into the inner agent.
+        foreach (var tarc in autoApproved)
+        {
+            state.CollectedApprovalResponses.Add(
+                tarc.CreateResponse(approved: true, reason: "Auto-approved by standing rule"));
+        }
+
+        // If every approval request was auto-approved, strip them all and signal the caller
+        // to re-invoke the inner agent immediately with the collected responses.
+        if (unapproved.Count == 0)
+        {
+            RemoveAllToolApprovalRequests(responseMessages);
+            this._sessionState.SaveState(session, state);
+            return true;
+        }
+
+        // Pass 2: Keep only the first unapproved request in the response (for the caller to decide).
+        //         Queue the remaining unapproved requests for subsequent one-at-a-time delivery.
+        //         Remove all auto-approved and queued items from the response messages.
+        var toRemove = new HashSet<ToolApprovalRequestContent>(autoApproved);
+        if (unapproved.Count > 1)
+        {
+            for (int i = 1; i < unapproved.Count; i++)
+            {
+                toRemove.Add(unapproved[i]);
+                state.QueuedApprovalRequests.Add(unapproved[i]);
+            }
+        }
+
+        // Walk messages in reverse and strip marked items.
+        for (int i = responseMessages.Count - 1; i >= 0; i--)
+        {
+            var message = responseMessages[i];
+
+            // Quick check: does this message contain any items to remove?
+            bool hasRemovable = false;
+            foreach (var content in message.Contents)
+            {
+                if (content is ToolApprovalRequestContent tarc && toRemove.Contains(tarc))
+                {
+                    hasRemovable = true;
+                    break;
+                }
+            }
+
+            if (!hasRemovable)
+            {
+                continue;
+            }
+
+            // Filter out the marked items, keeping everything else.
+            var remaining = new List<AIContent>(message.Contents.Count);
+            foreach (var content in message.Contents)
+            {
+                if (content is ToolApprovalRequestContent tarc && toRemove.Contains(tarc))
+                {
+                    continue;
+                }
+
+                remaining.Add(content);
+            }
+
+            // Remove the message entirely if it's now empty, otherwise replace with filtered clone.
+            if (remaining.Count == 0)
+            {
+                responseMessages.RemoveAt(i);
+            }
+            else
+            {
+                var clonedMessage = message.Clone();
+                clonedMessage.Contents = remaining;
+                responseMessages[i] = clonedMessage;
+            }
+        }
+
+        this._sessionState.SaveState(session, state);
+        return false;
+    }
+
+    /// <summary>
+    /// Removes all <see cref="ToolApprovalRequestContent"/> items from response messages.
+    /// </summary>
+    private static void RemoveAllToolApprovalRequests(IList<ChatMessage> responseMessages)
+    {
+        // Walk messages in reverse so we can safely remove by index.
+        for (int i = responseMessages.Count - 1; i >= 0; i--)
+        {
+            var message = responseMessages[i];
+
+            // Quick check: does this message contain any approval requests?
+            bool hasTarc = false;
+            foreach (var content in message.Contents)
+            {
+                if (content is ToolApprovalRequestContent)
+                {
+                    hasTarc = true;
+                    break;
+                }
+            }
+
+            if (!hasTarc)
+            {
+                continue;
+            }
+
+            // Keep only non-approval content.
+            var remaining = new List<AIContent>(message.Contents.Count);
+            foreach (var content in message.Contents)
+            {
+                if (content is not ToolApprovalRequestContent)
+                {
+                    remaining.Add(content);
+                }
+            }
+
+            // Remove the message entirely if it's now empty, otherwise replace with filtered clone.
+            if (remaining.Count == 0)
+            {
+                responseMessages.RemoveAt(i);
+            }
+            else
+            {
+                var clonedMessage = message.Clone();
+                clonedMessage.Contents = remaining;
+                responseMessages[i] = clonedMessage;
+            }
+        }
+    }
+
+    /// <summary>
+    /// Scans input messages for <see cref="AlwaysApproveToolApprovalResponseContent"/> instances,
+    /// extracts standing approval rules, and replaces them in-place with the unwrapped inner
+    /// <see cref="ToolApprovalResponseContent"/>, preserving content ordering.
+    /// </summary>
+    private static List<ChatMessage> UnwrapAlwaysApproveResponses(
+        IEnumerable<ChatMessage> messages,
+        ToolApprovalState state,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        var messageList = messages as IList<ChatMessage> ?? new List<ChatMessage>(messages);
+        var result = new List<ChatMessage>(messageList.Count);
+        bool anyModified = false;
+
+        foreach (var message in messageList)
+        {
+            // Quick check: does this message contain any AlwaysApprove wrappers?
+            bool hasAlwaysApprove = false;
+            foreach (var content in message.Contents)
+            {
+                if (content is AlwaysApproveToolApprovalResponseContent)
+                {
+                    hasAlwaysApprove = true;
+                    break;
+                }
+            }
+
+            if (!hasAlwaysApprove)
+            {
+                result.Add(message);
+                continue;
+            }
+
+            // Walk content items, replacing each AlwaysApprove wrapper with its inner response
+            // while extracting the standing approval rule into state.
+            var newContents = new List<AIContent>(message.Contents.Count);
+            foreach (var content in message.Contents)
+            {
+                if (content is AlwaysApproveToolApprovalResponseContent alwaysApprove)
+                {
+                    // Extract and store the standing approval rule.
+                    if (alwaysApprove.InnerResponse.ToolCall is FunctionCallContent toolCall)
+                    {
+                        if (alwaysApprove.AlwaysApproveTool)
+                        {
+                            AddRuleIfNotExists(state, new ToolApprovalRule { ToolName = toolCall.Name });
+                        }
+                        else if (alwaysApprove.AlwaysApproveToolWithArguments)
+                        {
+                            AddRuleIfNotExists(state, new ToolApprovalRule
+                            {
+                                ToolName = toolCall.Name,
+                                Arguments = SerializeArguments(toolCall.Arguments, jsonSerializerOptions),
+                            });
+                        }
+                    }
+
+                    // Replace the wrapper with the unwrapped inner response, preserving position.
+                    newContents.Add(alwaysApprove.InnerResponse);
+                }
+                else
+                {
+                    newContents.Add(content);
+                }
+            }
+
+            // Clone the original message so all metadata is preserved, then replace contents.
+            var clonedMessage = message.Clone();
+            clonedMessage.Contents = newContents;
+            result.Add(clonedMessage);
+            anyModified = true;
+        }
+
+        // Avoid allocating a new list if nothing was modified.
+        return anyModified ? result : (messageList as List<ChatMessage> ?? messageList.ToList());
+    }
+
+    /// <summary>
+    /// Determines whether a tool approval request matches any of the stored rules.
+    /// </summary>
+    internal static bool MatchesRule(
+        ToolApprovalRequestContent request,
+        IReadOnlyList<ToolApprovalRule> rules,
+        JsonSerializerOptions jsonSerializerOptions)
+    {
+        if (request.ToolCall is not FunctionCallContent functionCall)
+        {
+            return false;
+        }
+
+        foreach (var rule in rules)
+        {
+            if (!string.Equals(rule.ToolName, functionCall.Name, StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            // Tool-level rule: matches any arguments
+            if (rule.Arguments is null)
+            {
+                return true;
+            }
+
+            // Tool+arguments rule: exact match on all argument values
+            if (ArgumentsMatch(rule.Arguments, functionCall.Arguments, jsonSerializerOptions))
+            {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    /// <summary>
+    /// Compares stored rule arguments against actual function call arguments for an exact match.
+    /// </summary>
+    private static bool ArgumentsMatch(IDictionary<string, string> ruleArguments, IDictionary<string, object?>? callArguments, JsonSerializerOptions jsonSerializerOptions)
+    {
+        if (callArguments is null)
+        {
+            return ruleArguments.Count == 0;
+        }
+
+        if (ruleArguments.Count != callArguments.Count)
+        {
+            return false;
+        }
+
+        foreach (var kvp in ruleArguments)
+        {
+            if (!callArguments.TryGetValue(kvp.Key, out var callValue))
+            {
+                return false;
+            }
+
+            var serializedCallValue = SerializeArgumentValue(callValue, jsonSerializerOptions);
+            if (!string.Equals(kvp.Value, serializedCallValue, StringComparison.Ordinal))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+
+    /// <summary>
+    /// Serializes function call arguments to a string dictionary for storage and comparison.
+    /// </summary>
+    private static Dictionary<string, string>? SerializeArguments(IDictionary<string, object?>? arguments, JsonSerializerOptions jsonSerializerOptions)
+    {
+        if (arguments is null || arguments.Count == 0)
+        {
+            return null;
+        }
+
+        var serialized = new Dictionary<string, string>(arguments.Count, StringComparer.Ordinal);
+        foreach (var kvp in arguments)
+        {
+            serialized[kvp.Key] = SerializeArgumentValue(kvp.Value, jsonSerializerOptions);
+        }
+
+        return serialized;
+    }
+
+    /// <summary>
+    /// Serializes a single argument value to its JSON string representation.
+    /// </summary>
+    private static string SerializeArgumentValue(object? value, JsonSerializerOptions jsonSerializerOptions)
+    {
+        if (value is null)
+        {
+            return "null";
+        }
+
+        if (value is JsonElement jsonElement)
+        {
+            return jsonElement.GetRawText();
+        }
+
+        return JsonSerializer.Serialize(value, jsonSerializerOptions.GetTypeInfo(value.GetType()));
+    }
+
+    /// <summary>
+    /// Adds a rule to the state if an equivalent rule does not already exist.
+    /// </summary>
+    private static void AddRuleIfNotExists(ToolApprovalState state, ToolApprovalRule newRule)
+    {
+        foreach (var existingRule in state.Rules)
+        {
+            if (!string.Equals(existingRule.ToolName, newRule.ToolName, StringComparison.Ordinal))
+            {
+                continue;
+            }
+
+            if (existingRule.Arguments is null && newRule.Arguments is null)
+            {
+                return; // Duplicate tool-level rule
+            }
+
+            if (existingRule.Arguments is not null && newRule.Arguments is not null &&
+                ArgumentDictionariesEqual(existingRule.Arguments, newRule.Arguments))
+            {
+                return; // Duplicate tool+args rule
+            }
+        }
+
+        state.Rules.Add(newRule);
+    }
+
+    /// <summary>
+    /// Compares two string dictionaries for equality.
+    /// </summary>
+    private static bool ArgumentDictionariesEqual(IDictionary<string, string> a, IDictionary<string, string> b)
+    {
+        if (a.Count != b.Count)
+        {
+            return false;
+        }
+
+        foreach (var kvp in a)
+        {
+            if (!b.TryGetValue(kvp.Key, out var bValue) || !string.Equals(kvp.Value, bValue, StringComparison.Ordinal))
+            {
+                return false;
+            }
+        }
+
+        return true;
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalAgentBuilderExtensions.cs

@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Provides extension methods for adding tool approval middleware to <see cref="AIAgentBuilder"/> instances.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public static class ToolApprovalAgentBuilderExtensions
+{
+    /// <summary>
+    /// Adds tool approval middleware to the agent pipeline, enabling "don't ask again" approval behavior.
+    /// </summary>
+    /// <param name="builder">The <see cref="AIAgentBuilder"/> to which tool approval support will be added.</param>
+    /// <param name="jsonSerializerOptions">
+    /// Optional <see cref="JsonSerializerOptions"/> used for serializing argument values when storing rules
+    /// and for persisting state. When <see langword="null"/>, <see cref="AgentJsonUtilities.DefaultOptions"/> is used.
+    /// </param>
+    /// <returns>The <see cref="AIAgentBuilder"/> with tool approval middleware added, enabling method chaining.</returns>
+    /// <exception cref="System.ArgumentNullException"><paramref name="builder"/> is <see langword="null"/>.</exception>
+    /// <remarks>
+    /// <para>
+    /// The <see cref="ToolApprovalAgent"/> middleware intercepts tool approval flows between the caller and the inner agent.
+    /// When a caller responds with an <see cref="AlwaysApproveToolApprovalResponseContent"/>, the middleware records a standing
+    /// approval rule so that future matching tool calls are auto-approved without user interaction.
+    /// </para>
+    /// </remarks>
+    public static AIAgentBuilder UseToolApproval(
+        this AIAgentBuilder builder,
+        JsonSerializerOptions? jsonSerializerOptions = null)
+        => Throw.IfNull(builder).Use(innerAgent => new ToolApprovalAgent(innerAgent, jsonSerializerOptions));
+}

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalRequestContentExtensions.cs

@@ -0,0 +1,65 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+using Microsoft.Shared.Diagnostics;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Provides extension methods on <see cref="ToolApprovalRequestContent"/> for creating
+/// <see cref="AlwaysApproveToolApprovalResponseContent"/> instances that instruct the
+/// <see cref="ToolApprovalAgent"/> middleware to record standing approval rules.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+public static class ToolApprovalRequestContentExtensions
+{
+    /// <summary>
+    /// Creates an approved <see cref="AlwaysApproveToolApprovalResponseContent"/> that also
+    /// instructs the middleware to always approve future calls to the same tool,
+    /// regardless of the arguments provided.
+    /// </summary>
+    /// <param name="request">The tool approval request to respond to.</param>
+    /// <param name="reason">An optional reason for the approval.</param>
+    /// <returns>
+    /// An <see cref="AlwaysApproveToolApprovalResponseContent"/> wrapping an approved
+    /// <see cref="ToolApprovalResponseContent"/> with the <see cref="AlwaysApproveToolApprovalResponseContent.AlwaysApproveTool"/>
+    /// flag set to <see langword="true"/>.
+    /// </returns>
+    public static AlwaysApproveToolApprovalResponseContent CreateAlwaysApproveToolResponse(
+        this ToolApprovalRequestContent request,
+        string? reason = null)
+    {
+        _ = Throw.IfNull(request);
+
+        return new AlwaysApproveToolApprovalResponseContent(
+            request.CreateResponse(approved: true, reason),
+            alwaysApproveTool: true,
+            alwaysApproveToolWithArguments: false);
+    }
+
+    /// <summary>
+    /// Creates an approved <see cref="AlwaysApproveToolApprovalResponseContent"/> that also
+    /// instructs the middleware to always approve future calls to the same tool
+    /// with the exact same arguments.
+    /// </summary>
+    /// <param name="request">The tool approval request to respond to.</param>
+    /// <param name="reason">An optional reason for the approval.</param>
+    /// <returns>
+    /// An <see cref="AlwaysApproveToolApprovalResponseContent"/> wrapping an approved
+    /// <see cref="ToolApprovalResponseContent"/> with the <see cref="AlwaysApproveToolApprovalResponseContent.AlwaysApproveToolWithArguments"/>
+    /// flag set to <see langword="true"/>.
+    /// </returns>
+    public static AlwaysApproveToolApprovalResponseContent CreateAlwaysApproveToolWithArgumentsResponse(
+        this ToolApprovalRequestContent request,
+        string? reason = null)
+    {
+        _ = Throw.IfNull(request);
+
+        return new AlwaysApproveToolApprovalResponseContent(
+            request.CreateResponse(approved: true, reason),
+            alwaysApproveTool: false,
+            alwaysApproveToolWithArguments: true);
+    }
+}

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalRule.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents a standing approval rule for automatically approving tool calls
+/// without requiring explicit user approval each time.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A rule can match tool calls in two ways:
+/// <list type="bullet">
+/// <item><b>Tool-level</b>: When <see cref="Arguments"/> is <see langword="null"/>,
+/// all calls to the tool identified by <see cref="ToolName"/> are auto-approved.</item>
+/// <item><b>Tool+arguments</b>: When <see cref="Arguments"/> is non-null,
+/// only calls to the specified tool with exactly matching argument values are auto-approved.</item>
+/// </list>
+/// </para>
+/// </remarks>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class ToolApprovalRule
+{
+    /// <summary>
+    /// Gets or sets the name of the tool function that this rule applies to.
+    /// </summary>
+    [JsonPropertyName("toolName")]
+    public string ToolName { get; set; } = string.Empty;
+
+    /// <summary>
+    /// Gets or sets the specific argument values that must match for this rule to apply.
+    /// When <see langword="null"/>, the rule applies to all invocations of the tool
+    /// regardless of arguments.
+    /// </summary>
+    /// <remarks>
+    /// Argument values are stored as their JSON-serialized string representations
+    /// for reliable comparison.
+    /// </remarks>
+    [JsonPropertyName("arguments")]
+    public IDictionary<string, string>? Arguments { get; set; }
+}

dotnet/src/Microsoft.Agents.AI/Harness/ToolApproval/ToolApprovalState.cs

@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Diagnostics.CodeAnalysis;
+using System.Text.Json.Serialization;
+using Microsoft.Extensions.AI;
+using Microsoft.Shared.DiagnosticIds;
+
+namespace Microsoft.Agents.AI;
+
+/// <summary>
+/// Represents the persisted state of standing tool approval rules,
+/// stored in the session's <see cref="AgentSessionStateBag"/>.
+/// </summary>
+[Experimental(DiagnosticIds.Experiments.AgentsAIExperiments)]
+internal sealed class ToolApprovalState
+{
+    /// <summary>
+    /// Gets or sets the list of standing approval rules.
+    /// </summary>
+    [JsonPropertyName("rules")]
+    public List<ToolApprovalRule> Rules { get; set; } = new();
+
+    /// <summary>
+    /// Gets or sets the list of collected approval responses (both auto-approved and user-approved)
+    /// that are pending injection into the next inbound call to the inner agent.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Responses are collected during a queue cycle: when the inner agent returns multiple tool approval
+    /// requests, auto-approved ones and user-approved ones are accumulated here. Once all queued requests
+    /// are resolved, the collected responses are injected alongside the caller's messages so the inner
+    /// agent receives all tool responses together.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("collectedApprovalResponses")]
+    public List<ToolApprovalResponseContent> CollectedApprovalResponses { get; set; } = new();
+
+    /// <summary>
+    /// Gets or sets the list of queued tool approval requests that have not yet been
+    /// presented to the caller.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// When the inner agent returns multiple unapproved tool approval requests, only the first
+    /// is returned to the caller. The remaining requests are stored here and presented one at a
+    /// time on subsequent calls, allowing the caller's "always approve" rules to take effect on
+    /// later items in the same batch.
+    /// </para>
+    /// </remarks>
+    [JsonPropertyName("queuedApprovalRequests")]
+    public List<ToolApprovalRequestContent> QueuedApprovalRequests { get; set; } = new();
+}

dotnet/src/Microsoft.Agents.AI/Microsoft.Agents.AI.csproj

@@ -26,6 +26,7 @@
     <PackageReference Include="Microsoft.Extensions.Compliance.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.VectorData.Abstractions" />
     <PackageReference Include="Microsoft.Extensions.DependencyInjection.Abstractions" />
+    <PackageReference Include="Microsoft.Extensions.FileSystemGlobbing" />
     <PackageReference Include="Microsoft.Extensions.Logging.Abstractions" />
     <PackageReference Include="Microsoft.ML.Tokenizers" />
     <PackageReference Include="System.Diagnostics.DiagnosticSource" />

dotnet/tests/Microsoft.Agents.AI.UnitTests/Compaction/ContextWindowCompactionStrategyTests.cs

@@ -0,0 +1,219 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Threading.Tasks;
+using Microsoft.Agents.AI.Compaction;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.UnitTests.Compaction;
+
+/// <summary>
+/// Contains tests for the <see cref="ContextWindowCompactionStrategy"/> class.
+/// </summary>
+public class ContextWindowCompactionStrategyTests
+{
+    [Fact]
+    public void Constructor_ValidParameters_SetsProperties()
+    {
+        // Arrange & Act
+        var strategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: 1_050_000,
+            maxOutputTokens: 128_000);
+
+        // Assert
+        Assert.Equal(1_050_000, strategy.MaxContextWindowTokens);
+        Assert.Equal(128_000, strategy.MaxOutputTokens);
+        Assert.Equal(922_000, strategy.InputBudgetTokens);
+        Assert.Equal(ContextWindowCompactionStrategy.DefaultToolEvictionThreshold, strategy.ToolEvictionThreshold);
+        Assert.Equal(ContextWindowCompactionStrategy.DefaultTruncationThreshold, strategy.TruncationThreshold);
+    }
+
+    [Fact]
+    public void Constructor_CustomThresholds_SetsProperties()
+    {
+        // Arrange & Act
+        var strategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: 1_000_000,
+            maxOutputTokens: 100_000,
+            toolEvictionThreshold: 0.3,
+            truncationThreshold: 0.6);
+
+        // Assert
+        Assert.Equal(900_000, strategy.InputBudgetTokens);
+        Assert.Equal(0.3, strategy.ToolEvictionThreshold);
+        Assert.Equal(0.6, strategy.TruncationThreshold);
+    }
+
+    [Theory]
+    [InlineData(0, 100)]        // maxContextWindowTokens <= 0
+    [InlineData(-1, 100)]       // maxContextWindowTokens negative
+    public void Constructor_InvalidContextWindow_Throws(int contextWindow, int maxOutput)
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentOutOfRangeException>(() =>
+            new ContextWindowCompactionStrategy(contextWindow, maxOutput));
+    }
+
+    [Theory]
+    [InlineData(1000, -1)]       // maxOutputTokens negative
+    [InlineData(1000, 1000)]     // maxOutputTokens == contextWindow
+    [InlineData(1000, 1001)]     // maxOutputTokens > contextWindow
+    public void Constructor_InvalidOutputTokens_Throws(int contextWindow, int maxOutput)
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentOutOfRangeException>(() =>
+            new ContextWindowCompactionStrategy(contextWindow, maxOutput));
+    }
+
+    [Theory]
+    [InlineData(0.0)]   // Zero threshold
+    [InlineData(-0.1)]  // Negative threshold
+    [InlineData(1.1)]   // Over 1.0
+    public void Constructor_InvalidToolEvictionThreshold_Throws(double threshold)
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentOutOfRangeException>(() =>
+            new ContextWindowCompactionStrategy(1000, 100, toolEvictionThreshold: threshold));
+    }
+
+    [Theory]
+    [InlineData(0.0)]   // Zero threshold
+    [InlineData(-0.1)]  // Negative threshold
+    [InlineData(1.1)]   // Over 1.0
+    public void Constructor_InvalidTruncationThreshold_Throws(double threshold)
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentOutOfRangeException>(() =>
+            new ContextWindowCompactionStrategy(1000, 100, truncationThreshold: threshold));
+    }
+
+    [Fact]
+    public void Constructor_TruncationBelowToolEviction_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentOutOfRangeException>(() =>
+            new ContextWindowCompactionStrategy(1000, 100, toolEvictionThreshold: 0.8, truncationThreshold: 0.5));
+    }
+
+    [Fact]
+    public async Task CompactAsync_BelowToolEvictionThreshold_NoCompactionAsync()
+    {
+        // Arrange — input budget = 900 tokens, tool eviction at 450, truncation at 720
+        // A few short messages should be well below any threshold.
+        var strategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: 1000,
+            maxOutputTokens: 100);
+
+        CompactionMessageIndex index = CompactionMessageIndex.Create(
+        [
+            new ChatMessage(ChatRole.User, "Hello"),
+            new ChatMessage(ChatRole.Assistant, "Hi there!"),
+        ]);
+
+        // Act
+        bool result = await strategy.CompactAsync(index);
+
+        // Assert
+        Assert.False(result);
+        Assert.Equal(2, index.IncludedGroupCount);
+    }
+
+    [Fact]
+    public async Task CompactAsync_AboveTruncationThreshold_TruncatesOldestAsync()
+    {
+        // Arrange — use a budget of 5 tokens with truncation at 80% = 4 token threshold.
+        // Even the shortest messages will exceed this, ensuring truncation fires.
+        var strategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: 10,
+            maxOutputTokens: 5,
+            toolEvictionThreshold: 0.5,
+            truncationThreshold: 0.8);
+
+        // Verify internal budget calculation
+        Assert.Equal(5, strategy.InputBudgetTokens);
+
+        CompactionMessageIndex index = CompactionMessageIndex.Create(
+        [
+            new ChatMessage(ChatRole.User, "First user message"),
+            new ChatMessage(ChatRole.Assistant, "First response"),
+            new ChatMessage(ChatRole.User, "Second user message"),
+            new ChatMessage(ChatRole.Assistant, "Second response"),
+        ]);
+
+        int groupsBefore = index.IncludedGroupCount;
+        int tokensBefore = index.IncludedTokenCount;
+
+        // Verify tokens actually exceed the truncation threshold (80% of 5 = 4)
+        Assert.True(tokensBefore > 4, $"Expected tokens > 4 but got {tokensBefore}");
+        Assert.True(groupsBefore > 1, $"Expected groups > 1 but got {groupsBefore}");
+
+        // Act
+        bool result = await strategy.CompactAsync(index);
+
+        // Assert — with tokens well above a 4-token threshold, truncation should fire
+        Assert.True(result, $"Expected compaction to occur. Tokens before: {tokensBefore}, groups before: {groupsBefore}, NonSystemGroups: {index.IncludedNonSystemGroupCount}");
+        Assert.True(index.IncludedGroupCount < groupsBefore);
+    }
+
+    [Fact]
+    public async Task CompactAsync_ToolCallsAboveEvictionThreshold_CollapsesToolCallsAsync()
+    {
+        // Arrange — very small budget so tool eviction fires.
+        // Input budget = 5, tool eviction at 50% = 2 token threshold.
+        var strategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: 10,
+            maxOutputTokens: 5,
+            toolEvictionThreshold: 0.5,
+            truncationThreshold: 0.9);
+
+        // Build messages with a tool call group: assistant with FunctionCallContent + tool result
+        var assistantMessage = new ChatMessage(ChatRole.Assistant, [new FunctionCallContent("call1", "get_data", arguments: new Dictionary<string, object?> { ["query"] = "test" })]);
+        var toolResultMessage = new ChatMessage(ChatRole.Tool, [new FunctionResultContent("call1", "Here is a long result with many words to ensure we exceed the token threshold")]);
+        var userMessage = new ChatMessage(ChatRole.User, "What did you find?");
+        var assistantResponse = new ChatMessage(ChatRole.Assistant, "Based on the results I found information.");
+
+        CompactionMessageIndex index = CompactionMessageIndex.Create(
+        [
+            assistantMessage,
+            toolResultMessage,
+            userMessage,
+            assistantResponse,
+        ]);
+
+        // Act
+        bool result = await strategy.CompactAsync(index);
+
+        // Assert — compaction should succeed for tool calls above the eviction threshold.
+        // Do not assert on IncludedTokenCount because tool-result compaction preserves content
+        // in summary form and tokenization can make the count stay the same or increase.
+        Assert.True(result);
+    }
+
+    [Fact]
+    public void Constructor_EqualThresholds_Succeeds()
+    {
+        // Arrange & Act — truncation == tool eviction should be valid
+        var strategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: 1000,
+            maxOutputTokens: 100,
+            toolEvictionThreshold: 0.7,
+            truncationThreshold: 0.7);
+
+        // Assert
+        Assert.Equal(0.7, strategy.ToolEvictionThreshold);
+        Assert.Equal(0.7, strategy.TruncationThreshold);
+    }
+
+    [Fact]
+    public void Constructor_ZeroMaxOutputTokens_FullBudget()
+    {
+        // Arrange & Act
+        var strategy = new ContextWindowCompactionStrategy(
+            maxContextWindowTokens: 1_000_000,
+            maxOutputTokens: 0);
+
+        // Assert — entire context window is the input budget
+        Assert.Equal(1_000_000, strategy.InputBudgetTokens);
+    }
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/AgentMode/AgentModeProviderTests.cs

@@ -0,0 +1,665 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Moq;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Unit tests for the <see cref="AgentModeProvider"/> class.
+/// </summary>
+public class AgentModeProviderTests
+{
+    #region ProvideAIContextAsync Tests
+
+    /// <summary>
+    /// Verify that the provider returns tools and instructions.
+    /// </summary>
+    [Fact]
+    public async Task ProvideAIContextAsync_ReturnsToolsAndInstructionsAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.NotNull(result.Instructions);
+        Assert.NotNull(result.Tools);
+        Assert.Equal(2, result.Tools!.Count());
+    }
+
+    /// <summary>
+    /// Verify that the instructions include the current mode.
+    /// </summary>
+    [Fact]
+    public async Task ProvideAIContextAsync_InstructionsIncludeCurrentModeAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Contains("plan", result.Instructions);
+    }
+
+    #endregion
+
+    #region SetMode Tool Tests
+
+    /// <summary>
+    /// Verify that SetMode changes the mode.
+    /// </summary>
+    [Fact]
+    public async Task SetMode_ChangesModeAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction setMode = GetTool(tools, "AgentMode_Set");
+
+        // Act
+        await setMode.InvokeAsync(new AIFunctionArguments() { ["mode"] = "execute" });
+
+        // Assert
+        Assert.Equal("execute", state.CurrentMode);
+    }
+
+    /// <summary>
+    /// Verify that SetMode returns a confirmation message.
+    /// </summary>
+    [Fact]
+    public async Task SetMode_ReturnsConfirmationAsync()
+    {
+        // Arrange
+        var (tools, _) = await CreateToolsWithStateAsync();
+        AIFunction setMode = GetTool(tools, "AgentMode_Set");
+
+        // Act
+        object? result = await setMode.InvokeAsync(new AIFunctionArguments() { ["mode"] = "execute" });
+
+        // Assert
+        Assert.Equal("Mode changed to \"execute\".", GetStringResult(result));
+    }
+
+    /// <summary>
+    /// Verify that SetMode with an unsupported value throws and does not persist the mode.
+    /// </summary>
+    [Fact]
+    public async Task SetMode_InvalidMode_ThrowsAsync()
+    {
+        // Arrange
+        var (tools, provider, session) = await CreateToolsWithProviderAndSessionAsync();
+        AIFunction setMode = GetTool(tools, "AgentMode_Set");
+        AIFunction getMode = GetTool(tools, "AgentMode_Get");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await setMode.InvokeAsync(new AIFunctionArguments() { ["mode"] = "foo" }));
+
+        // Verify mode was not changed from default
+        object? currentMode = await getMode.InvokeAsync(new AIFunctionArguments());
+        Assert.Equal("plan", GetStringResult(currentMode));
+    }
+
+    #endregion
+
+    #region GetMode Tool Tests
+
+    /// <summary>
+    /// Verify that GetMode returns the default mode.
+    /// </summary>
+    [Fact]
+    public async Task GetMode_ReturnsDefaultModeAsync()
+    {
+        // Arrange
+        var (tools, _) = await CreateToolsWithStateAsync();
+        AIFunction getMode = GetTool(tools, "AgentMode_Get");
+
+        // Act
+        object? result = await getMode.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        Assert.Equal("plan", GetStringResult(result));
+    }
+
+    /// <summary>
+    /// Verify that GetMode returns the mode after SetMode.
+    /// </summary>
+    [Fact]
+    public async Task GetMode_ReturnsUpdatedModeAfterSetAsync()
+    {
+        // Arrange
+        var (tools, _) = await CreateToolsWithStateAsync();
+        AIFunction setMode = GetTool(tools, "AgentMode_Set");
+        AIFunction getMode = GetTool(tools, "AgentMode_Get");
+
+        // Act
+        await setMode.InvokeAsync(new AIFunctionArguments() { ["mode"] = "execute" });
+        object? result = await getMode.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        Assert.Equal("execute", GetStringResult(result));
+    }
+
+    #endregion
+
+    #region Public Helper Method Tests
+
+    /// <summary>
+    /// Verify that the public GetMode helper returns the default mode.
+    /// </summary>
+    [Fact]
+    public void PublicGetMode_ReturnsDefaultMode()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var session = new ChatClientAgentSession();
+
+        // Act
+        string mode = provider.GetMode(session);
+
+        // Assert
+        Assert.Equal("plan", mode);
+    }
+
+    /// <summary>
+    /// Verify that the public SetMode helper changes the mode.
+    /// </summary>
+    [Fact]
+    public void PublicSetMode_ChangesMode()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var session = new ChatClientAgentSession();
+
+        // Act
+        provider.SetMode(session, "execute");
+        string mode = provider.GetMode(session);
+
+        // Assert
+        Assert.Equal("execute", mode);
+    }
+
+    /// <summary>
+    /// Verify that the public SetMode helper throws for an unsupported value and does not persist the mode.
+    /// </summary>
+    [Fact]
+    public void PublicSetMode_InvalidMode_Throws()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var session = new ChatClientAgentSession();
+
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => provider.SetMode(session, "foo"));
+
+        // Verify mode was not changed from default
+        string mode = provider.GetMode(session);
+        Assert.Equal("plan", mode);
+    }
+
+    /// <summary>
+    /// Verify that public helper changes are reflected in tool results.
+    /// </summary>
+    [Fact]
+    public async Task PublicSetMode_ReflectedInToolResultsAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+
+        // Set mode via public helper
+        provider.SetMode(session, "execute");
+
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+        AIFunction getMode = GetTool(result.Tools!, "AgentMode_Get");
+        object? modeResult = await getMode.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        Assert.Equal("execute", GetStringResult(modeResult));
+        Assert.Contains("execute", result.Instructions);
+    }
+
+    #endregion
+
+    #region State Persistence Tests
+
+    /// <summary>
+    /// Verify that state persists across invocations.
+    /// </summary>
+    [Fact]
+    public async Task State_PersistsAcrossInvocationsAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act — first invocation changes mode
+        AIContext result1 = await provider.InvokingAsync(context);
+        AIFunction setMode = GetTool(result1.Tools!, "AgentMode_Set");
+        await setMode.InvokeAsync(new AIFunctionArguments() { ["mode"] = "execute" });
+
+        // Second invocation should see the updated mode
+        AIContext result2 = await provider.InvokingAsync(context);
+        AIFunction getMode = GetTool(result2.Tools!, "AgentMode_Get");
+        object? modeResult = await getMode.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        Assert.Equal("execute", GetStringResult(modeResult));
+        Assert.Contains("execute", result2.Instructions);
+    }
+
+    #endregion
+
+    #region Options Tests
+
+    /// <summary>
+    /// Verify that custom instructions override the default.
+    /// </summary>
+    [Fact]
+    public async Task Options_CustomInstructions_OverridesDefaultAsync()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions { Instructions = "Custom mode instructions." };
+        var provider = new AgentModeProvider(options);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Equal("Custom mode instructions.", result.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that custom modes are used.
+    /// </summary>
+    [Fact]
+    public void Options_CustomModes_AreUsed()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes =
+            [
+                new AgentModeProviderOptions.AgentMode("draft", "Drafting mode."),
+                new AgentModeProviderOptions.AgentMode("review", "Review mode."),
+            ],
+        };
+        var provider = new AgentModeProvider(options);
+        var session = new ChatClientAgentSession();
+
+        // Act
+        string mode = provider.GetMode(session);
+
+        // Assert — default mode is first in list
+        Assert.Equal("draft", mode);
+    }
+
+    /// <summary>
+    /// Verify that SetMode validates against custom modes.
+    /// </summary>
+    [Fact]
+    public void Options_CustomModes_SetModeValidatesAgainstList()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes =
+            [
+                new AgentModeProviderOptions.AgentMode("draft", "Drafting mode."),
+                new AgentModeProviderOptions.AgentMode("review", "Review mode."),
+            ],
+        };
+        var provider = new AgentModeProvider(options);
+        var session = new ChatClientAgentSession();
+
+        // Act — valid mode
+        provider.SetMode(session, "review");
+
+        // Assert
+        Assert.Equal("review", provider.GetMode(session));
+
+        // Act & Assert — invalid mode (plan is no longer valid)
+        Assert.Throws<ArgumentException>(() => provider.SetMode(session, "plan"));
+    }
+
+    /// <summary>
+    /// Verify that a custom default mode is used.
+    /// </summary>
+    [Fact]
+    public void Options_CustomDefaultMode_IsUsed()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes =
+            [
+                new AgentModeProviderOptions.AgentMode("draft", "Drafting mode."),
+                new AgentModeProviderOptions.AgentMode("review", "Review mode."),
+            ],
+            DefaultMode = "review",
+        };
+        var provider = new AgentModeProvider(options);
+        var session = new ChatClientAgentSession();
+
+        // Act
+        string mode = provider.GetMode(session);
+
+        // Assert
+        Assert.Equal("review", mode);
+    }
+
+    /// <summary>
+    /// Verify that an invalid default mode throws.
+    /// </summary>
+    [Fact]
+    public void Options_InvalidDefaultMode_Throws()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes =
+            [
+                new AgentModeProviderOptions.AgentMode("draft", "Drafting mode."),
+            ],
+            DefaultMode = "nonexistent",
+        };
+
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new AgentModeProvider(options));
+    }
+
+    /// <summary>
+    /// Verify that an empty modes list throws.
+    /// </summary>
+    [Fact]
+    public void Options_EmptyModes_Throws()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes = [],
+        };
+
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new AgentModeProvider(options));
+    }
+
+    /// <summary>
+    /// Verify that custom modes appear in generated instructions.
+    /// </summary>
+    [Fact]
+    public async Task Options_CustomModes_AppearInInstructionsAsync()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes =
+            [
+                new AgentModeProviderOptions.AgentMode("draft", "Drafting mode description."),
+                new AgentModeProviderOptions.AgentMode("review", "Review mode description."),
+            ],
+        };
+        var provider = new AgentModeProvider(options);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Contains("draft", result.Instructions);
+        Assert.Contains("Drafting mode description.", result.Instructions);
+        Assert.Contains("review", result.Instructions);
+        Assert.Contains("Review mode description.", result.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that AgentMode requires non-empty name and description.
+    /// </summary>
+    [Fact]
+    public void AgentMode_RequiresNameAndDescription()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new AgentModeProviderOptions.AgentMode("", "desc"));
+        Assert.Throws<ArgumentException>(() => new AgentModeProviderOptions.AgentMode("name", ""));
+        Assert.ThrowsAny<ArgumentException>(() => new AgentModeProviderOptions.AgentMode(null!, "desc"));
+        Assert.ThrowsAny<ArgumentException>(() => new AgentModeProviderOptions.AgentMode("name", null!));
+    }
+
+    /// <summary>
+    /// Verify that duplicate mode names throw.
+    /// </summary>
+    [Fact]
+    public void Options_DuplicateModeNames_Throws()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes =
+            [
+                new AgentModeProviderOptions.AgentMode("draft", "First draft."),
+                new AgentModeProviderOptions.AgentMode("draft", "Second draft."),
+            ],
+        };
+
+        // Act & Assert
+        var ex = Assert.Throws<ArgumentException>(() => new AgentModeProvider(options));
+        Assert.Contains("duplicate", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    /// <summary>
+    /// Verify that a null entry in the modes list throws.
+    /// </summary>
+    [Fact]
+    public void Options_NullModeEntry_Throws()
+    {
+        // Arrange
+        var options = new AgentModeProviderOptions
+        {
+            Modes = new List<AgentModeProviderOptions.AgentMode> { null! },
+        };
+
+        // Act & Assert
+        var ex = Assert.Throws<ArgumentException>(() => new AgentModeProvider(options));
+        Assert.Contains("must not be null", ex.Message, StringComparison.OrdinalIgnoreCase);
+    }
+
+    #endregion
+
+    #region External Mode Change Notification Tests
+
+    /// <summary>
+    /// Verify that an external mode change injects a notification message.
+    /// </summary>
+    [Fact]
+    public async Task ExternalModeChange_InjectsNotificationMessageAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+
+        // Change mode externally (simulating /mode command)
+        provider.SetMode(session, "execute");
+
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.NotNull(result.Messages);
+        Assert.Single(result.Messages!);
+        ChatMessage message = result.Messages!.First();
+        Assert.Equal(ChatRole.User, message.Role);
+        Assert.Contains("plan", message.Text);
+        Assert.Contains("execute", message.Text);
+    }
+
+    /// <summary>
+    /// Verify that the notification is only injected once (cleared after first read).
+    /// </summary>
+    [Fact]
+    public async Task ExternalModeChange_NotificationClearedAfterFirstReadAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+        provider.SetMode(session, "execute");
+
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act — first call should have the notification
+        AIContext result1 = await provider.InvokingAsync(context);
+        Assert.NotNull(result1.Messages);
+
+        // Second call should NOT have the notification
+        AIContext result2 = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Null(result2.Messages);
+    }
+
+    /// <summary>
+    /// Verify that tool-based mode change does not inject a notification message.
+    /// </summary>
+    [Fact]
+    public async Task ToolModeChange_DoesNotInjectNotificationAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // First call to initialize
+        AIContext result1 = await provider.InvokingAsync(context);
+        AIFunction setMode = GetTool(result1.Tools!, "AgentMode_Set");
+
+        // Change mode via the tool (agent-initiated)
+        await setMode.InvokeAsync(new AIFunctionArguments() { ["mode"] = "execute" });
+
+        // Act — next call should NOT have a notification
+        AIContext result2 = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Null(result2.Messages);
+    }
+
+    /// <summary>
+    /// Verify that setting the same mode externally does not inject a notification.
+    /// </summary>
+    [Fact]
+    public async Task ExternalModeChange_SameMode_NoNotificationAsync()
+    {
+        // Arrange
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+
+        // Set to same default mode
+        provider.SetMode(session, "plan");
+
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Null(result.Messages);
+    }
+
+    #endregion
+
+    #region Helper Methods
+
+    private static async Task<(IEnumerable<AITool> Tools, AgentModeState State)> CreateToolsWithStateAsync()
+    {
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Retrieve the state from the session to verify mutations
+        session.StateBag.TryGetValue<AgentModeState>("AgentModeProvider", out var state, AgentJsonUtilities.DefaultOptions);
+
+        return (result.Tools!, state!);
+    }
+
+    private static async Task<(IEnumerable<AITool> Tools, AgentModeProvider Provider, AgentSession Session)> CreateToolsWithProviderAndSessionAsync()
+    {
+        var provider = new AgentModeProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        AIContext result = await provider.InvokingAsync(context);
+        return (result.Tools!, provider, session);
+    }
+
+    private static AIFunction GetTool(IEnumerable<AITool> tools, string name)
+    {
+        return (AIFunction)tools.First(t => t is AIFunction f && f.Name == name);
+    }
+
+    private static string GetStringResult(object? result)
+    {
+        var element = Assert.IsType<JsonElement>(result);
+        return element.GetString()!;
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/FileAccess/FileAccessProviderTests.cs

@@ -0,0 +1,604 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Moq;
+
+namespace Microsoft.Agents.AI.UnitTests.Harness.FileAccess;
+
+public class FileAccessProviderTests
+{
+    #region Constructor Validation
+
+    [Fact]
+    public void Constructor_NullFileStore_Throws()
+    {
+        Assert.Throws<ArgumentNullException>(() => new FileAccessProvider(null!));
+    }
+
+    [Fact]
+    public void Constructor_WithDefaults_Succeeds()
+    {
+        // Act
+        var provider = new FileAccessProvider(new InMemoryAgentFileStore());
+
+        // Assert
+        Assert.NotNull(provider);
+    }
+
+    #endregion
+
+    #region ProvideAIContextAsync Tests
+
+    [Fact]
+    public async Task ProvideAIContextAsync_ReturnsToolsAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+
+        // Assert — 5 tools: SaveFile, ReadFile, DeleteFile, ListFiles, SearchFiles
+        Assert.Equal(5, tools.Count());
+    }
+
+    [Fact]
+    public async Task ProvideAIContextAsync_ReturnsInstructionsAsync()
+    {
+        // Arrange
+        var provider = new FileAccessProvider(new InMemoryAgentFileStore());
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.NotNull(result.Instructions);
+        Assert.Contains("File Access", result.Instructions);
+        Assert.Contains("FileAccess_", result.Instructions);
+        Assert.Contains("persist beyond the current session", result.Instructions);
+    }
+
+    [Fact]
+    public async Task ProvideAIContextAsync_DoesNotInjectMessagesAsync()
+    {
+        // Arrange — FileAccessProvider should never inject messages (unlike FileMemoryProvider).
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        var provider = new FileAccessProvider(store);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Null(result.Messages);
+    }
+
+    [Fact]
+    public void StateKeys_ReturnsEmpty()
+    {
+        // Arrange — FileAccessProvider has no session state.
+        var provider = new FileAccessProvider(new InMemoryAgentFileStore());
+
+        // Act
+        var keys = provider.StateKeys;
+
+        // Assert
+        Assert.Empty(keys);
+    }
+
+    #endregion
+
+    #region SaveFile Tests
+
+    [Fact]
+    public async Task SaveFile_CreatesFileAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var tools = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        // Act
+        await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Test content",
+        });
+
+        // Assert
+        var content = await store.ReadFileAsync("notes.md");
+        Assert.Equal("Test content", content);
+    }
+
+    [Fact]
+    public async Task SaveFile_DoesNotCreateDescriptionSidecarAsync()
+    {
+        // Arrange — FileAccessProvider should never create description sidecar files.
+        var store = new InMemoryAgentFileStore();
+        var tools = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        // Act
+        await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "research.md",
+            ["content"] = "Long research content...",
+        });
+
+        // Assert — file exists, no description sidecar
+        Assert.Equal("Long research content...", await store.ReadFileAsync("research.md"));
+        Assert.Null(await store.ReadFileAsync("research_description.md"));
+    }
+
+    [Fact]
+    public async Task SaveFile_ExistingFile_WithoutOverwrite_ReturnsErrorAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var tools = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Original",
+        });
+
+        // Act — try to save again without overwrite
+        var result = await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Updated",
+        });
+
+        // Assert — original content preserved, error message returned
+        Assert.Equal("Original", await store.ReadFileAsync("notes.md"));
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Contains("already exists", text);
+    }
+
+    [Fact]
+    public async Task SaveFile_ExistingFile_WithOverwrite_SucceedsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var tools = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Original",
+        });
+
+        // Act — save again with overwrite=true
+        await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Updated",
+            ["overwrite"] = true,
+        });
+
+        // Assert
+        Assert.Equal("Updated", await store.ReadFileAsync("notes.md"));
+    }
+
+    [Fact]
+    public async Task SaveFile_ReturnsConfirmationAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        // Act
+        var result = await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "test.md",
+            ["content"] = "Content",
+        });
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Contains("saved", text);
+    }
+
+    #endregion
+
+    #region ReadFile Tests
+
+    [Fact]
+    public async Task ReadFile_ExistingFile_ReturnsContentAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Stored content");
+        var tools = await CreateToolsAsync(store);
+        var readFile = GetTool(tools, "FileAccess_ReadFile");
+
+        // Act
+        var result = await InvokeToolAsync(readFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+        });
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Equal("Stored content", text);
+    }
+
+    [Fact]
+    public async Task ReadFile_NonExistent_ReturnsNotFoundMessageAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var readFile = GetTool(tools, "FileAccess_ReadFile");
+
+        // Act
+        var result = await InvokeToolAsync(readFile, new AIFunctionArguments
+        {
+            ["fileName"] = "nonexistent.md",
+        });
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Contains("not found", text);
+    }
+
+    #endregion
+
+    #region DeleteFile Tests
+
+    [Fact]
+    public async Task DeleteFile_ExistingFile_DeletesAndReturnsConfirmationAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        var tools = await CreateToolsAsync(store);
+        var deleteFile = GetTool(tools, "FileAccess_DeleteFile");
+
+        // Act
+        var result = await InvokeToolAsync(deleteFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+        });
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Contains("deleted", text);
+        Assert.False(await store.FileExistsAsync("notes.md"));
+    }
+
+    [Fact]
+    public async Task DeleteFile_NonExistent_ReturnsNotFoundAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var deleteFile = GetTool(tools, "FileAccess_DeleteFile");
+
+        // Act
+        var result = await InvokeToolAsync(deleteFile, new AIFunctionArguments
+        {
+            ["fileName"] = "missing.md",
+        });
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Contains("not found", text);
+    }
+
+    #endregion
+
+    #region ListFiles Tests
+
+    [Fact]
+    public async Task ListFiles_ReturnsFileNamesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        await store.WriteFileAsync("data.txt", "Data");
+        var tools = await CreateToolsAsync(store);
+        var listFiles = GetTool(tools, "FileAccess_ListFiles");
+
+        // Act
+        var result = await InvokeToolAsync(listFiles, new AIFunctionArguments());
+
+        // Assert — returns plain list of file names (no description properties)
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Equal(2, entries.Count);
+        Assert.Contains(entries, e => e.GetString() == "data.txt");
+        Assert.Contains(entries, e => e.GetString() == "notes.md");
+    }
+
+    [Fact]
+    public async Task ListFiles_DoesNotFilterDescriptionFilesAsync()
+    {
+        // Arrange — FileAccessProvider doesn't know about description sidecars, so all files are visible.
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        await store.WriteFileAsync("notes_description.md", "Description");
+        var tools = await CreateToolsAsync(store);
+        var listFiles = GetTool(tools, "FileAccess_ListFiles");
+
+        // Act
+        var result = await InvokeToolAsync(listFiles, new AIFunctionArguments());
+
+        // Assert — both files should be visible
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Equal(2, entries.Count);
+    }
+
+    [Fact]
+    public async Task ListFiles_EmptyStore_ReturnsEmptyListAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var listFiles = GetTool(tools, "FileAccess_ListFiles");
+
+        // Act
+        var result = await InvokeToolAsync(listFiles, new AIFunctionArguments());
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Empty(entries);
+    }
+
+    #endregion
+
+    #region SearchFiles Tests
+
+    [Fact]
+    public async Task SearchFiles_FindsMatchingContentAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Important research findings about AI");
+        var tools = await CreateToolsAsync(store);
+        var searchFiles = GetTool(tools, "FileAccess_SearchFiles");
+
+        // Act
+        var result = await InvokeToolAsync(searchFiles, new AIFunctionArguments
+        {
+            ["regexPattern"] = "research findings",
+            ["filePattern"] = "",
+        });
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Single(entries);
+        Assert.Equal("notes.md", entries[0].GetProperty("fileName").GetString());
+        Assert.True(entries[0].TryGetProperty("matchingLines", out var matchingLines));
+        Assert.True(matchingLines.GetArrayLength() > 0);
+    }
+
+    [Fact]
+    public async Task SearchFiles_WithFilePattern_FiltersResultsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Important data");
+        await store.WriteFileAsync("data.txt", "Important data");
+        var tools = await CreateToolsAsync(store);
+        var searchFiles = GetTool(tools, "FileAccess_SearchFiles");
+
+        // Act
+        var result = await InvokeToolAsync(searchFiles, new AIFunctionArguments
+        {
+            ["regexPattern"] = "Important",
+            ["filePattern"] = "*.md",
+        });
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Single(entries);
+        Assert.Equal("notes.md", entries[0].GetProperty("fileName").GetString());
+    }
+
+    [Fact]
+    public async Task SearchFiles_NoMatches_ReturnsEmptyAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "No matching content here");
+        var tools = await CreateToolsAsync(store);
+        var searchFiles = GetTool(tools, "FileAccess_SearchFiles");
+
+        // Act
+        var result = await InvokeToolAsync(searchFiles, new AIFunctionArguments
+        {
+            ["regexPattern"] = "nonexistent pattern xyz",
+        });
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Empty(entries);
+    }
+
+    #endregion
+
+    #region Path Traversal Protection
+
+    [Fact]
+    public async Task SaveFile_PathTraversal_ThrowsAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeToolAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = "../escape.md",
+                ["content"] = "Content",
+            }));
+    }
+
+    [Fact]
+    public async Task SaveFile_AbsolutePath_ThrowsAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeToolAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = "/etc/passwd",
+                ["content"] = "Content",
+            }));
+    }
+
+    [Fact]
+    public async Task SaveFile_DriveRootedPath_ThrowsAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeToolAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = "C:\\temp\\file.md",
+                ["content"] = "Content",
+            }));
+    }
+
+    [Fact]
+    public async Task SaveFile_DoubleDotsInFileName_AllowedAsync()
+    {
+        // Arrange — "notes..md" is not a path traversal attempt.
+        var store = new InMemoryAgentFileStore();
+        var tools = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileAccess_SaveFile");
+
+        // Act
+        await InvokeToolAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes..md",
+            ["content"] = "Content",
+        });
+
+        // Assert
+        Assert.Equal("Content", await store.ReadFileAsync("notes..md"));
+    }
+
+    [Fact]
+    public async Task ReadFile_PathTraversal_ThrowsAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var readFile = GetTool(tools, "FileAccess_ReadFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeToolAsync(readFile, new AIFunctionArguments
+            {
+                ["fileName"] = "../../etc/passwd",
+            }));
+    }
+
+    [Fact]
+    public async Task DeleteFile_PathTraversal_ThrowsAsync()
+    {
+        // Arrange
+        var tools = await CreateToolsAsync();
+        var deleteFile = GetTool(tools, "FileAccess_DeleteFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeToolAsync(deleteFile, new AIFunctionArguments
+            {
+                ["fileName"] = "../escape.md",
+            }));
+    }
+
+    #endregion
+
+    #region Options Tests
+
+    [Fact]
+    public async Task Options_CustomInstructions_OverridesDefaultAsync()
+    {
+        // Arrange
+        var options = new FileAccessProviderOptions { Instructions = "Custom file access instructions." };
+        var provider = new FileAccessProvider(new InMemoryAgentFileStore(), options: options);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Equal("Custom file access instructions.", result.Instructions);
+    }
+
+    [Fact]
+    public async Task Options_Null_UsesDefaultInstructionsAsync()
+    {
+        // Arrange
+        var provider = new FileAccessProvider(new InMemoryAgentFileStore());
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Contains("File Access", result.Instructions);
+    }
+
+    #endregion
+
+    #region Helper Methods
+
+    private static async Task<IEnumerable<AITool>> CreateToolsAsync(InMemoryAgentFileStore? store = null)
+    {
+        var provider = new FileAccessProvider(store ?? new InMemoryAgentFileStore());
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        AIContext result = await provider.InvokingAsync(context);
+        return result.Tools!;
+    }
+
+    private static AIFunction GetTool(IEnumerable<AITool> tools, string name)
+    {
+        return (AIFunction)tools.First(t => t is AIFunction f && f.Name == name);
+    }
+
+    /// <summary>
+    /// Invokes a tool. Since <see cref="FileAccessProvider"/> does not use session state,
+    /// the tools don't need an ambient <see cref="AIAgent.CurrentRunContext"/>.
+    /// </summary>
+    private static async Task<object?> InvokeToolAsync(AIFunction tool, AIFunctionArguments arguments)
+    {
+        return await tool.InvokeAsync(arguments);
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/FileMemory/FileMemoryProviderTests.cs

@@ -0,0 +1,916 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Moq;
+
+namespace Microsoft.Agents.AI.UnitTests.Harness.FileMemory;
+
+public class FileMemoryProviderTests
+{
+    #region Constructor Validation
+
+    [Fact]
+    public void Constructor_NullFileStore_Throws()
+    {
+        Assert.Throws<ArgumentNullException>(() => new FileMemoryProvider(null!));
+    }
+
+    [Fact]
+    public void Constructor_WithDefaults_Succeeds()
+    {
+        // Act
+        var provider = new FileMemoryProvider(new InMemoryAgentFileStore());
+
+        // Assert
+        Assert.NotNull(provider);
+    }
+
+    [Fact]
+    public void Constructor_WithStateInitializer_Succeeds()
+    {
+        // Act
+        var provider = new FileMemoryProvider(
+            new InMemoryAgentFileStore(),
+            _ => new FileMemoryState { WorkingFolder = "custom" });
+
+        // Assert
+        Assert.NotNull(provider);
+    }
+
+    #endregion
+
+    #region ProvideAIContextAsync Tests
+
+    [Fact]
+    public async Task ProvideAIContextAsync_ReturnsToolsAsync()
+    {
+        // Arrange
+        var (tools, _, session) = await CreateToolsAsync();
+
+        // Assert - 5 tools: SaveFile, ReadFile, DeleteFile, ListFiles, SearchFiles
+        Assert.Equal(5, tools.Count());
+    }
+
+    [Fact]
+    public async Task ProvideAIContextAsync_ReturnsInstructionsAsync()
+    {
+        // Arrange
+        var provider = new FileMemoryProvider(new InMemoryAgentFileStore());
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.NotNull(result.Instructions);
+        Assert.Contains("file-based memory", result.Instructions);
+        Assert.Contains("compacted", result.Instructions);
+    }
+
+    #endregion
+
+    #region SaveFile Tests
+
+    [Fact]
+    public async Task SaveFile_CreatesFileAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Test content",
+            ["description"] = "",
+        }, session);
+
+        // Assert
+        var content = await store.ReadFileAsync("notes.md");
+        Assert.Equal("Test content", content);
+    }
+
+    [Fact]
+    public async Task SaveFile_WithDescription_CreatesBothFilesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "research.md",
+            ["content"] = "Long research content...",
+            ["description"] = "Summary of research findings",
+        }, session);
+
+        // Assert
+        var content = await store.ReadFileAsync("research.md");
+        Assert.Equal("Long research content...", content);
+        var desc = await store.ReadFileAsync("research_description.md");
+        Assert.Equal("Summary of research findings", desc);
+    }
+
+    [Fact]
+    public async Task SaveFile_WithoutDescription_DeletesStaleDescriptionAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Save with description first.
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Original",
+            ["description"] = "Old description",
+        }, session);
+        Assert.NotNull(await store.ReadFileAsync("notes_description.md"));
+
+        // Act — overwrite without description.
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Updated",
+        }, session);
+
+        // Assert — stale description file is removed.
+        Assert.Equal("Updated", await store.ReadFileAsync("notes.md"));
+        Assert.Null(await store.ReadFileAsync("notes_description.md"));
+    }
+
+    [Fact]
+    public async Task SaveFile_WithCustomState_CreatesInSubfolderAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, state, session) = await CreateToolsAsync(store, _ => new FileMemoryState { WorkingFolder = "session123" });
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Session content",
+            ["description"] = "",
+        }, session);
+
+        // Assert
+        Assert.Equal("session123", state.WorkingFolder);
+        var content = await store.ReadFileAsync("session123/notes.md");
+        Assert.Equal("Session content", content);
+    }
+
+    #endregion
+
+    #region ReadFile Tests
+
+    [Fact]
+    public async Task ReadFile_ExistingFile_ReturnsContentAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Stored content");
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var readFile = GetTool(tools, "FileMemory_ReadFile");
+
+        // Act
+        var result = await InvokeWithRunContextAsync(readFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+        }, session);
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Equal("Stored content", text);
+    }
+
+    [Fact]
+    public async Task ReadFile_NonExistent_ReturnsNotFoundMessageAsync()
+    {
+        // Arrange
+        var (tools, _, session) = await CreateToolsAsync();
+        var readFile = GetTool(tools, "FileMemory_ReadFile");
+
+        // Act
+        var result = await InvokeWithRunContextAsync(readFile, new AIFunctionArguments
+        {
+            ["fileName"] = "nonexistent.md",
+        }, session);
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Contains("not found", text);
+    }
+
+    #endregion
+
+    #region DeleteFile Tests
+
+    [Fact]
+    public async Task DeleteFile_ExistingFile_DeletesAndReturnsConfirmationAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var deleteFile = GetTool(tools, "FileMemory_DeleteFile");
+
+        // Act
+        var result = await InvokeWithRunContextAsync(deleteFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+        }, session);
+
+        // Assert
+        var text = Assert.IsType<JsonElement>(result).GetString();
+        Assert.Contains("deleted", text);
+        Assert.False(await store.FileExistsAsync("notes.md"));
+    }
+
+    [Fact]
+    public async Task DeleteFile_AlsoDeletesDescriptionFileAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        await store.WriteFileAsync("notes_description.md", "Description");
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var deleteFile = GetTool(tools, "FileMemory_DeleteFile");
+
+        // Act
+        await InvokeWithRunContextAsync(deleteFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+        }, session);
+
+        // Assert
+        Assert.False(await store.FileExistsAsync("notes.md"));
+        Assert.False(await store.FileExistsAsync("notes_description.md"));
+    }
+
+    #endregion
+
+    #region ListFiles Tests
+
+    [Fact]
+    public async Task ListFiles_ReturnsFilesWithDescriptionsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        await store.WriteFileAsync("notes_description.md", "A description");
+        await store.WriteFileAsync("other.md", "Other content");
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var listFiles = GetTool(tools, "FileMemory_ListFiles");
+
+        // Act
+        var result = await InvokeWithRunContextAsync(listFiles, new AIFunctionArguments(), session);
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Equal(2, entries.Count);
+
+        var notesEntry = entries.First(e => e.GetProperty("fileName").GetString() == "notes.md");
+        Assert.Equal("A description", notesEntry.GetProperty("description").GetString());
+
+        var otherEntry = entries.First(e => e.GetProperty("fileName").GetString() == "other.md");
+        Assert.False(otherEntry.TryGetProperty("description", out _));
+    }
+
+    [Fact]
+    public async Task ListFiles_HidesDescriptionFilesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+        await store.WriteFileAsync("notes_description.md", "Desc");
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var listFiles = GetTool(tools, "FileMemory_ListFiles");
+
+        // Act
+        var result = await InvokeWithRunContextAsync(listFiles, new AIFunctionArguments(), session);
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Single(entries);
+        Assert.Equal("notes.md", entries[0].GetProperty("fileName").GetString());
+    }
+
+    #endregion
+
+    #region SearchFiles Tests
+
+    [Fact]
+    public async Task SearchFiles_FindsMatchingContentAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Important research findings about AI");
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var searchFiles = GetTool(tools, "FileMemory_SearchFiles");
+
+        // Act
+        var result = await InvokeWithRunContextAsync(searchFiles, new AIFunctionArguments
+        {
+            ["regexPattern"] = "research findings",
+            ["filePattern"] = "",
+        }, session);
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Single(entries);
+        Assert.Equal("notes.md", entries[0].GetProperty("fileName").GetString());
+        Assert.True(entries[0].TryGetProperty("matchingLines", out var matchingLines));
+        Assert.True(matchingLines.GetArrayLength() > 0);
+    }
+
+    [Fact]
+    public async Task SearchFiles_WithFilePattern_FiltersResultsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Important data");
+        await store.WriteFileAsync("data.txt", "Important data");
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var searchFiles = GetTool(tools, "FileMemory_SearchFiles");
+
+        // Act
+        var result = await InvokeWithRunContextAsync(searchFiles, new AIFunctionArguments
+        {
+            ["regexPattern"] = "Important",
+            ["filePattern"] = "*.md",
+        }, session);
+
+        // Assert
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Single(entries);
+        Assert.Equal("notes.md", entries[0].GetProperty("fileName").GetString());
+    }
+
+    #endregion
+
+    #region State Initializer Tests
+
+    [Fact]
+    public async Task CustomStateInitializer_SetsWorkingFolderAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (_, state, _) = await CreateToolsAsync(store, _ => new FileMemoryState { WorkingFolder = "user42" });
+
+        // Assert
+        Assert.Equal("user42", state.WorkingFolder);
+    }
+
+    [Fact]
+    public async Task DefaultStateInitializer_UsesEmptyWorkingFolderAsync()
+    {
+        // Arrange
+        var (_, state, _) = await CreateToolsAsync();
+
+        // Assert
+        Assert.Equal(string.Empty, state.WorkingFolder);
+    }
+
+    [Fact]
+    public async Task State_PersistsAcrossInvocationsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var provider = new FileMemoryProvider(store, _ => new FileMemoryState { WorkingFolder = "persistent" });
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act - first invocation initializes state
+        await provider.InvokingAsync(context);
+        session.StateBag.TryGetValue<FileMemoryState>("FileMemoryProvider", out var state1, AgentJsonUtilities.DefaultOptions);
+
+        // Second invocation should reuse the same folder
+        await provider.InvokingAsync(context);
+        session.StateBag.TryGetValue<FileMemoryState>("FileMemoryProvider", out var state2, AgentJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(state1);
+        Assert.NotNull(state2);
+        Assert.Equal(state1!.WorkingFolder, state2!.WorkingFolder);
+    }
+
+    #endregion
+
+    #region Path Traversal Protection
+
+    [Fact]
+    public async Task SaveFile_PathTraversal_ThrowsAsync()
+    {
+        // Arrange
+        var (tools, _, session) = await CreateToolsAsync();
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = "../escape.md",
+                ["content"] = "Content",
+                ["description"] = "",
+            }, session));
+    }
+
+    [Fact]
+    public async Task SaveFile_AbsolutePath_ThrowsAsync()
+    {
+        // Arrange
+        var (tools, _, session) = await CreateToolsAsync();
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = "/etc/passwd",
+                ["content"] = "Content",
+                ["description"] = "",
+            }, session));
+    }
+
+    [Fact]
+    public async Task SaveFile_DriveRootedPath_ThrowsAsync()
+    {
+        // Arrange
+        var (tools, _, session) = await CreateToolsAsync();
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(async () =>
+            await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = "C:\\temp\\file.md",
+                ["content"] = "Content",
+            }, session));
+    }
+
+    [Fact]
+    public async Task SaveFile_DoubleDotsInFileName_AllowedAsync()
+    {
+        // Arrange — "notes..md" is not a path traversal attempt.
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes..md",
+            ["content"] = "Content",
+        }, session);
+
+        // Assert
+        Assert.Equal("Content", await store.ReadFileAsync("notes..md"));
+    }
+
+    #endregion
+
+    #region Memory Index Tests
+
+    [Fact]
+    public async Task SaveFile_CreatesMemoryIndexAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Test content",
+        }, session);
+
+        // Assert — memories.md should exist and contain the file entry.
+        string? index = await store.ReadFileAsync("memories.md");
+        Assert.NotNull(index);
+        Assert.Contains("**notes.md**", index);
+    }
+
+    [Fact]
+    public async Task SaveFile_WithDescription_IndexIncludesDescriptionAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "research.md",
+            ["content"] = "Research data",
+            ["description"] = "Key findings",
+        }, session);
+
+        // Assert
+        string? index = await store.ReadFileAsync("memories.md");
+        Assert.NotNull(index);
+        Assert.Contains("**research.md**: Key findings", index);
+    }
+
+    [Fact]
+    public async Task DeleteFile_UpdatesMemoryIndexAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+        var deleteFile = GetTool(tools, "FileMemory_DeleteFile");
+
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Content",
+        }, session);
+
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "other.md",
+            ["content"] = "Other",
+        }, session);
+
+        // Act
+        await InvokeWithRunContextAsync(deleteFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+        }, session);
+
+        // Assert — index should only contain other.md
+        string? index = await store.ReadFileAsync("memories.md");
+        Assert.NotNull(index);
+        Assert.DoesNotContain("notes.md", index);
+        Assert.Contains("**other.md**", index);
+    }
+
+    [Fact]
+    public async Task MemoryIndex_CappedAt50EntriesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+
+        // Act — save 55 files
+        for (int i = 0; i < 55; i++)
+        {
+            await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = $"file{i:D3}.md",
+                ["content"] = $"Content {i}",
+            }, session);
+        }
+
+        // Assert — index should have at most 50 entries
+        string? index = await store.ReadFileAsync("memories.md");
+        Assert.NotNull(index);
+
+        int entryCount = 0;
+        foreach (string line in index!.Split('\n'))
+        {
+            if (line.StartsWith("- **", StringComparison.Ordinal))
+            {
+                entryCount++;
+            }
+        }
+
+        Assert.Equal(50, entryCount);
+    }
+
+    [Fact]
+    public async Task ListFiles_HidesMemoryIndexAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+        var listFiles = GetTool(tools, "FileMemory_ListFiles");
+
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "notes.md",
+            ["content"] = "Content",
+        }, session);
+
+        // Act
+        var result = await InvokeWithRunContextAsync(listFiles, new AIFunctionArguments(), session);
+
+        // Assert — memories.md should not appear in the listing
+        var entries = Assert.IsType<JsonElement>(result).EnumerateArray().ToList();
+        Assert.Single(entries);
+        Assert.Equal("notes.md", entries[0].GetProperty("fileName").GetString());
+    }
+
+    [Fact]
+    public async Task ProvideAIContextAsync_InjectsMemoryIndexMessageAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var provider = new FileMemoryProvider(store);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+
+        // First, save a file via tool invocation to create the index.
+#pragma warning disable MAAI001
+        var initContext = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+        AIContext initResult = await provider.InvokingAsync(initContext);
+        var saveFile = GetTool(initResult.Tools!, "FileMemory_SaveFile");
+        await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+        {
+            ["fileName"] = "research.md",
+            ["content"] = "Data",
+            ["description"] = "Research summary",
+        }, session);
+
+        // Act — invoke the provider again; it should now inject the memory index.
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.NotNull(result.Messages);
+        var messages = result.Messages!.ToList();
+        Assert.Single(messages);
+        Assert.Equal(ChatRole.User, messages[0].Role);
+        Assert.Contains("memory index", messages[0].Text, StringComparison.OrdinalIgnoreCase);
+        Assert.Contains("research.md", messages[0].Text);
+    }
+
+    [Fact]
+    public async Task ProvideAIContextAsync_NoFiles_NoMessageInjectedAsync()
+    {
+        // Arrange
+        var provider = new FileMemoryProvider(new InMemoryAgentFileStore());
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert — no memories.md exists, so no message should be injected
+        Assert.Null(result.Messages);
+    }
+
+    #endregion
+
+    #region Helper Methods
+
+    private static FileMemoryProvider CreateProvider(InMemoryAgentFileStore? store = null, Func<AgentSession?, FileMemoryState>? stateInitializer = null)
+    {
+        return new FileMemoryProvider(store ?? new InMemoryAgentFileStore(), stateInitializer);
+    }
+
+    private static async Task<(IEnumerable<AITool> Tools, FileMemoryState State, AgentSession Session)> CreateToolsAsync(InMemoryAgentFileStore? store = null, Func<AgentSession?, FileMemoryState>? stateInitializer = null)
+    {
+        var provider = CreateProvider(store, stateInitializer);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        AIContext result = await provider.InvokingAsync(context);
+
+        session.StateBag.TryGetValue<FileMemoryState>("FileMemoryProvider", out var state, AgentJsonUtilities.DefaultOptions);
+
+        return (result.Tools!, state!, session);
+    }
+
+    private static AIFunction GetTool(IEnumerable<AITool> tools, string name)
+    {
+        return (AIFunction)tools.First(t => t is AIFunction f && f.Name == name);
+    }
+
+    /// <summary>
+    /// Invokes a tool within a mock <see cref="AIAgent.CurrentRunContext"/> so that
+    /// the tool methods can access the session via <c>AIAgent.CurrentRunContext?.Session</c>.
+    /// </summary>
+    /// <param name="tool">The tool to invoke.</param>
+    /// <param name="arguments">The arguments to pass to the tool.</param>
+    /// <param name="session">
+    /// An optional session to use in the run context. When provided, ensures the tool executes
+    /// against the same session whose state was initialized during <see cref="CreateToolsAsync"/>.
+    /// When <see langword="null"/>, a new session is created.
+    /// </param>
+    private static async Task<object?> InvokeWithRunContextAsync(AIFunction tool, AIFunctionArguments arguments, AgentSession? session = null)
+    {
+        var agent = new Mock<AIAgent>().Object;
+        session ??= new ChatClientAgentSession();
+        var messages = new List<ChatMessage>();
+
+        // Set up the ambient run context so tool methods can access the session.
+        var runContext = new AgentRunContext(agent, session, messages, null);
+
+        // Use reflection to set the protected static CurrentRunContext property.
+        var property = typeof(AIAgent).GetProperty("CurrentRunContext", System.Reflection.BindingFlags.Public | System.Reflection.BindingFlags.Static);
+        var setter = property!.GetSetMethod(true)!;
+        var previousContext = AIAgent.CurrentRunContext;
+        try
+        {
+            setter.Invoke(null, [runContext]);
+            return await tool.InvokeAsync(arguments);
+        }
+        finally
+        {
+            setter.Invoke(null, [previousContext]);
+        }
+    }
+
+    #endregion
+
+    #region Options Tests
+
+    /// <summary>
+    /// Verify that custom instructions override the default.
+    /// </summary>
+    [Fact]
+    public async Task Options_CustomInstructions_OverridesDefaultAsync()
+    {
+        // Arrange
+        var options = new FileMemoryProviderOptions { Instructions = "Custom file memory instructions." };
+        var provider = new FileMemoryProvider(new InMemoryAgentFileStore(), options: options);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Equal("Custom file memory instructions.", result.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that null options uses default instructions.
+    /// </summary>
+    [Fact]
+    public async Task Options_Null_UsesDefaultInstructionsAsync()
+    {
+        // Arrange
+        var provider = new FileMemoryProvider(new InMemoryAgentFileStore());
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Contains("file-based memory", result.Instructions);
+    }
+
+    #endregion
+
+    #region Thread Safety Tests
+
+    [Fact]
+    public async Task ConcurrentSaves_ProduceConsistentIndexAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+        const int FileCount = 20;
+
+        // Act — save multiple files in parallel.
+        var tasks = new Task[FileCount];
+        for (int i = 0; i < FileCount; i++)
+        {
+            int index = i;
+            tasks[i] = InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = $"file{index}.md",
+                ["content"] = $"Content {index}",
+                ["description"] = $"Description {index}",
+            }, session);
+        }
+
+        await Task.WhenAll(tasks);
+
+        // Assert — the memory index should contain all files.
+        string? indexContent = await store.ReadFileAsync("memories.md");
+        Assert.NotNull(indexContent);
+        for (int i = 0; i < FileCount; i++)
+        {
+            Assert.Contains($"**file{i}.md**", indexContent);
+        }
+    }
+
+    [Fact]
+    public async Task ConcurrentSaveAndDelete_ProduceConsistentIndexAsync()
+    {
+        // Arrange — pre-populate files that will be deleted.
+        var store = new InMemoryAgentFileStore();
+        var (tools, _, session) = await CreateToolsAsync(store);
+        var saveFile = GetTool(tools, "FileMemory_SaveFile");
+        var deleteFile = GetTool(tools, "FileMemory_DeleteFile");
+
+        for (int i = 0; i < 5; i++)
+        {
+            await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = $"delete{i}.md",
+                ["content"] = $"To be deleted {i}",
+            }, session);
+        }
+
+        // Act — concurrently save new files and delete existing ones.
+        var tasks = new List<Task>();
+        for (int i = 0; i < 5; i++)
+        {
+            int index = i;
+            tasks.Add(InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = $"keep{index}.md",
+                ["content"] = $"Kept {index}",
+            }, session));
+            tasks.Add(InvokeWithRunContextAsync(deleteFile, new AIFunctionArguments
+            {
+                ["fileName"] = $"delete{index}.md",
+            }, session));
+        }
+
+        await Task.WhenAll(tasks);
+
+        // Assert — index should contain only the kept files.
+        string? indexContent = await store.ReadFileAsync("memories.md");
+        Assert.NotNull(indexContent);
+        for (int i = 0; i < 5; i++)
+        {
+            Assert.Contains($"**keep{i}.md**", indexContent);
+            Assert.DoesNotContain($"**delete{i}.md**", indexContent);
+        }
+    }
+
+    [Fact]
+    public void Dispose_ReleasesResources()
+    {
+        // Arrange
+        var provider = new FileMemoryProvider(new InMemoryAgentFileStore());
+
+        // Act
+        provider.Dispose();
+
+        // Assert — calling Dispose again should not throw (idempotent SemaphoreSlim.Dispose).
+        provider.Dispose();
+    }
+
+    [Fact]
+    public async Task SaveFile_AfterDispose_ThrowsAsync()
+    {
+        // Arrange — create tools from a provider, then dispose the provider.
+        var store = new InMemoryAgentFileStore();
+        var provider = CreateProvider(store);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+        AIContext result = await provider.InvokingAsync(context);
+        var saveFile = GetTool(result.Tools!, "FileMemory_SaveFile");
+        provider.Dispose();
+
+        // Act & Assert — the disposed SemaphoreSlim should throw ObjectDisposedException.
+        await Assert.ThrowsAsync<ObjectDisposedException>(async () =>
+            await InvokeWithRunContextAsync(saveFile, new AIFunctionArguments
+            {
+                ["fileName"] = "notes.md",
+                ["content"] = "Should fail",
+            }, session));
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/FileStore/FileSystemAgentFileStoreTests.cs

@@ -0,0 +1,337 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.IO;
+using System.Text.RegularExpressions;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.UnitTests.Harness.FileMemory;
+
+public sealed class FileSystemAgentFileStoreTests : IDisposable
+{
+    private readonly string _rootDir;
+    private readonly FileSystemAgentFileStore _store;
+
+    public FileSystemAgentFileStoreTests()
+    {
+        this._rootDir = Path.Combine(Path.GetTempPath(), "FileSystemAgentFileStoreTests_" + Guid.NewGuid().ToString("N"));
+        this._store = new FileSystemAgentFileStore(this._rootDir);
+    }
+
+    public void Dispose()
+    {
+        if (Directory.Exists(this._rootDir))
+        {
+            Directory.Delete(this._rootDir, recursive: true);
+        }
+    }
+
+    #region Constructor
+
+    [Fact]
+    public void Constructor_CreatesRootDirectory()
+    {
+        // Assert
+        Assert.True(Directory.Exists(this._rootDir));
+    }
+
+    [Fact]
+    public void Constructor_NullRootDirectory_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>(() => new FileSystemAgentFileStore(null!));
+    }
+
+    [Fact]
+    public void Constructor_EmptyRootDirectory_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new FileSystemAgentFileStore(""));
+    }
+
+    [Fact]
+    public void Constructor_WhitespaceRootDirectory_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new FileSystemAgentFileStore("   "));
+    }
+
+    #endregion
+
+    #region Path Traversal Rejection
+
+    [Fact]
+    public async Task WriteFileAsync_DotDotSegment_ThrowsAsync()
+    {
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => this._store.WriteFileAsync("../escape.txt", "content"));
+    }
+
+    [Fact]
+    public async Task ReadFileAsync_AbsolutePath_ThrowsAsync()
+    {
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => this._store.ReadFileAsync("/etc/passwd"));
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_DriveRootedPath_ThrowsAsync()
+    {
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => this._store.DeleteFileAsync("C:\\temp\\file.txt"));
+    }
+
+    [Fact]
+    public async Task WriteFileAsync_DotSegment_ThrowsAsync()
+    {
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => this._store.WriteFileAsync("./file.txt", "content"));
+    }
+
+    [Fact]
+    public async Task WriteFileAsync_DoubleDotsInFileName_AllowedAsync()
+    {
+        // Arrange — "notes..md" contains ".." but is not a ".." segment
+        await this._store.WriteFileAsync("notes..md", "content");
+
+        // Act
+        string? result = await this._store.ReadFileAsync("notes..md");
+
+        // Assert
+        Assert.Equal("content", result);
+    }
+
+    [Fact]
+    public async Task WriteFileAsync_TrailingSlash_NormalizesAsync()
+    {
+        // Act — trailing slash is trimmed during normalization.
+        await this._store.WriteFileAsync("subdir/", "content");
+
+        // Assert — the file is accessible via the normalized name.
+        string? result = await this._store.ReadFileAsync("subdir");
+        Assert.Equal("content", result);
+    }
+
+    #endregion
+
+    #region Write and Read
+
+    [Fact]
+    public async Task WriteAndReadAsync_RoundTripsAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("test.txt", "hello world");
+
+        // Act
+        string? content = await this._store.ReadFileAsync("test.txt");
+
+        // Assert
+        Assert.Equal("hello world", content);
+    }
+
+    [Fact]
+    public async Task WriteFileAsync_OverwritesExistingAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("test.txt", "first");
+        await this._store.WriteFileAsync("test.txt", "second");
+
+        // Act
+        string? content = await this._store.ReadFileAsync("test.txt");
+
+        // Assert
+        Assert.Equal("second", content);
+    }
+
+    [Fact]
+    public async Task ReadFileAsync_NonExistent_ReturnsNullAsync()
+    {
+        // Act
+        string? content = await this._store.ReadFileAsync("missing.txt");
+
+        // Assert
+        Assert.Null(content);
+    }
+
+    #endregion
+
+    #region Delete
+
+    [Fact]
+    public async Task DeleteFileAsync_ExistingFile_ReturnsTrueAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("delete-me.txt", "content");
+
+        // Act
+        bool deleted = await this._store.DeleteFileAsync("delete-me.txt");
+
+        // Assert
+        Assert.True(deleted);
+        Assert.Null(await this._store.ReadFileAsync("delete-me.txt"));
+    }
+
+    [Fact]
+    public async Task DeleteFileAsync_NonExistent_ReturnsFalseAsync()
+    {
+        // Act
+        bool deleted = await this._store.DeleteFileAsync("nope.txt");
+
+        // Assert
+        Assert.False(deleted);
+    }
+
+    #endregion
+
+    #region FileExists
+
+    [Fact]
+    public async Task FileExistsAsync_ExistingFile_ReturnsTrueAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("exists.txt", "content");
+
+        // Act & Assert
+        Assert.True(await this._store.FileExistsAsync("exists.txt"));
+    }
+
+    [Fact]
+    public async Task FileExistsAsync_NonExistent_ReturnsFalseAsync()
+    {
+        // Act & Assert
+        Assert.False(await this._store.FileExistsAsync("missing.txt"));
+    }
+
+    #endregion
+
+    #region ListFiles
+
+    [Fact]
+    public async Task ListFilesAsync_ReturnsDirectChildrenOnlyAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("root.txt", "content");
+        await this._store.WriteFileAsync("sub/nested.txt", "content");
+
+        // Act
+        var files = await this._store.ListFilesAsync("");
+
+        // Assert
+        Assert.Single(files);
+        Assert.Equal("root.txt", files[0]);
+    }
+
+    [Fact]
+    public async Task ListFilesAsync_SubDirectory_ReturnsChildrenAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("sub/a.txt", "content");
+        await this._store.WriteFileAsync("sub/b.txt", "content");
+        await this._store.WriteFileAsync("other.txt", "content");
+
+        // Act
+        var files = await this._store.ListFilesAsync("sub");
+
+        // Assert
+        Assert.Equal(2, files.Count);
+        Assert.Contains("a.txt", files);
+        Assert.Contains("b.txt", files);
+    }
+
+    [Fact]
+    public async Task ListFilesAsync_NonExistentDirectory_ReturnsEmptyAsync()
+    {
+        // Act
+        var files = await this._store.ListFilesAsync("no-such-dir");
+
+        // Assert
+        Assert.Empty(files);
+    }
+
+    #endregion
+
+    #region CreateDirectory
+
+    [Fact]
+    public async Task CreateDirectoryAsync_CreatesOnDiskAsync()
+    {
+        // Act
+        await this._store.CreateDirectoryAsync("new-dir");
+
+        // Assert
+        Assert.True(Directory.Exists(Path.Combine(this._rootDir, "new-dir")));
+    }
+
+    #endregion
+
+    #region SearchFiles
+
+    [Fact]
+    public async Task SearchFilesAsync_FindsMatchAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("doc.md", "This has an error on line one.\nLine two is fine.");
+
+        // Act
+        var results = await this._store.SearchFilesAsync("", "error");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal("doc.md", results[0].FileName);
+        Assert.Single(results[0].MatchingLines);
+        Assert.Equal(1, results[0].MatchingLines[0].LineNumber);
+        Assert.Contains("error", results[0].Snippet);
+    }
+
+    [Fact]
+    public async Task SearchFilesAsync_GlobFilter_ExcludesNonMatchingAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("notes.md", "important info");
+        await this._store.WriteFileAsync("data.txt", "important info");
+
+        // Act
+        var results = await this._store.SearchFilesAsync("", "important", "*.md");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal("notes.md", results[0].FileName);
+    }
+
+    [Fact]
+    public async Task SearchFilesAsync_NoMatch_ReturnsEmptyAsync()
+    {
+        // Arrange
+        await this._store.WriteFileAsync("doc.md", "nothing here");
+
+        // Act
+        var results = await this._store.SearchFilesAsync("", "missing-pattern");
+
+        // Assert
+        Assert.Empty(results);
+    }
+
+    [Fact]
+    public async Task SearchFilesAsync_NonExistentDirectory_ReturnsEmptyAsync()
+    {
+        // Act
+        var results = await this._store.SearchFilesAsync("no-dir", "anything");
+
+        // Assert
+        Assert.Empty(results);
+    }
+
+    [Fact]
+    public async Task SearchFilesAsync_RegexTimeout_ThrowsOnBadPatternAsync()
+    {
+        // Arrange — write a file with content that triggers catastrophic backtracking.
+        // The pattern (a+)+$ with a string of 'a's followed by 'b' forces exponential backtracking.
+        await this._store.WriteFileAsync("trap.txt", new string('a', 30) + "b");
+
+        // Act & Assert — a known ReDoS pattern with backtracking
+        await Assert.ThrowsAsync<RegexMatchTimeoutException>(() =>
+            this._store.SearchFilesAsync("", "(a+)+$"));
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/FileStore/InMemoryAgentFileStoreTests.cs

@@ -0,0 +1,523 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.UnitTests.Harness.FileMemory;
+
+public class InMemoryAgentFileStoreTests
+{
+    [Fact]
+    public async Task WriteAndReadFile_ReturnsContentAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act
+        await store.WriteFileAsync("notes.md", "Hello world");
+        var content = await store.ReadFileAsync("notes.md");
+
+        // Assert
+        Assert.Equal("Hello world", content);
+    }
+
+    [Fact]
+    public async Task ReadFile_NonExistent_ReturnsNullAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act
+        var content = await store.ReadFileAsync("nonexistent.md");
+
+        // Assert
+        Assert.Null(content);
+    }
+
+    [Fact]
+    public async Task WriteFile_OverwritesExistingAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Original");
+
+        // Act
+        await store.WriteFileAsync("notes.md", "Updated");
+        var content = await store.ReadFileAsync("notes.md");
+
+        // Assert
+        Assert.Equal("Updated", content);
+    }
+
+    [Fact]
+    public async Task DeleteFile_ExistingFile_ReturnsTrueAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+
+        // Act
+        var deleted = await store.DeleteFileAsync("notes.md");
+
+        // Assert
+        Assert.True(deleted);
+        Assert.Null(await store.ReadFileAsync("notes.md"));
+    }
+
+    [Fact]
+    public async Task DeleteFile_NonExistent_ReturnsFalseAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act
+        var deleted = await store.DeleteFileAsync("nonexistent.md");
+
+        // Assert
+        Assert.False(deleted);
+    }
+
+    [Fact]
+    public async Task ListFiles_ReturnsDirectChildrenAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/file1.md", "Content 1");
+        await store.WriteFileAsync("folder/file2.md", "Content 2");
+        await store.WriteFileAsync("folder/sub/file3.md", "Content 3");
+        await store.WriteFileAsync("other/file4.md", "Content 4");
+
+        // Act
+        var files = await store.ListFilesAsync("folder");
+
+        // Assert
+        Assert.Equal(2, files.Count);
+        Assert.Contains("file1.md", files);
+        Assert.Contains("file2.md", files);
+    }
+
+    [Fact]
+    public async Task ListFiles_EmptyDirectory_ReturnsEmptyAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act
+        var files = await store.ListFilesAsync("empty");
+
+        // Assert
+        Assert.Empty(files);
+    }
+
+    [Fact]
+    public async Task ListFiles_RootDirectory_ReturnsRootFilesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("root.md", "Content");
+        await store.WriteFileAsync("folder/nested.md", "Content");
+
+        // Act
+        var files = await store.ListFilesAsync("");
+
+        // Assert
+        Assert.Single(files);
+        Assert.Equal("root.md", files[0]);
+    }
+
+    [Fact]
+    public async Task ListFiles_IncludesDescriptionFilesAsync()
+    {
+        // Arrange — the store is dumb; it returns all files including _description.md
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "Content");
+        await store.WriteFileAsync("folder/notes_description.md", "Desc");
+
+        // Act
+        var files = await store.ListFilesAsync("folder");
+
+        // Assert
+        Assert.Equal(2, files.Count);
+        Assert.Contains("notes.md", files);
+        Assert.Contains("notes_description.md", files);
+    }
+
+    [Fact]
+    public async Task FileExists_ExistingFile_ReturnsTrueAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("notes.md", "Content");
+
+        // Act & Assert
+        Assert.True(await store.FileExistsAsync("notes.md"));
+    }
+
+    [Fact]
+    public async Task FileExists_NonExistent_ReturnsFalseAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act & Assert
+        Assert.False(await store.FileExistsAsync("nonexistent.md"));
+    }
+
+    [Fact]
+    public async Task SearchFiles_FindsMatchingContentAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "The quick brown fox jumps over the lazy dog");
+        await store.WriteFileAsync("folder/other.md", "No match here");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "brown fox");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal("notes.md", results[0].FileName);
+        Assert.Contains("brown fox", results[0].Snippet);
+    }
+
+    [Fact]
+    public async Task SearchFiles_ReturnsMatchingLineNumbersAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "Line one\nLine two with match\nLine three\nLine four with match");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "match");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal(2, results[0].MatchingLines.Count);
+        Assert.Equal(2, results[0].MatchingLines[0].LineNumber);
+        Assert.Equal("Line two with match", results[0].MatchingLines[0].Line);
+        Assert.Equal(4, results[0].MatchingLines[1].LineNumber);
+        Assert.Equal("Line four with match", results[0].MatchingLines[1].Line);
+    }
+
+    [Fact]
+    public async Task SearchFiles_CaseInsensitiveAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "Important Data Here");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "important data");
+
+        // Assert
+        Assert.Single(results);
+    }
+
+    [Fact]
+    public async Task SearchFiles_SupportsRegexPatternAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "Error: something went wrong\nWarning: check this\nInfo: all good");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "error|warning");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal(2, results[0].MatchingLines.Count);
+        Assert.Equal(1, results[0].MatchingLines[0].LineNumber);
+        Assert.Equal(2, results[0].MatchingLines[1].LineNumber);
+    }
+
+    [Fact]
+    public async Task SearchFiles_SupportsRegexWithSpecialCharactersAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/code.cs", "var x = 42;\nvar y = 100;\nconst z = 7;");
+
+        // Act — regex matching lines starting with "var"
+        var results = await store.SearchFilesAsync("folder", @"^var\b");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal(2, results[0].MatchingLines.Count);
+    }
+
+    [Fact]
+    public async Task SearchFiles_WithGlobPattern_FiltersFilesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "Important data");
+        await store.WriteFileAsync("folder/data.txt", "Important data");
+        await store.WriteFileAsync("folder/code.cs", "Important data");
+
+        // Act — only search markdown files
+        var results = await store.SearchFilesAsync("folder", "Important", filePattern: "*.md");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal("notes.md", results[0].FileName);
+    }
+
+    [Fact]
+    public async Task SearchFiles_WithGlobPattern_MultipleExtensionsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "match here");
+        await store.WriteFileAsync("folder/data.txt", "match here");
+        await store.WriteFileAsync("folder/code.cs", "match here");
+
+        // Act — search both md and txt files
+        var resultsMd = await store.SearchFilesAsync("folder", "match", filePattern: "*.md");
+        var resultsTxt = await store.SearchFilesAsync("folder", "match", filePattern: "*.txt");
+
+        // Assert
+        Assert.Single(resultsMd);
+        Assert.Equal("notes.md", resultsMd[0].FileName);
+        Assert.Single(resultsTxt);
+        Assert.Equal("data.txt", resultsTxt[0].FileName);
+    }
+
+    [Fact]
+    public async Task SearchFiles_WithGlobPattern_PrefixMatchAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/research_ai.md", "findings");
+        await store.WriteFileAsync("folder/research_ml.md", "findings");
+        await store.WriteFileAsync("folder/notes.md", "findings");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "findings", filePattern: "research*");
+
+        // Assert
+        Assert.Equal(2, results.Count);
+        Assert.All(results, r => Assert.StartsWith("research", r.FileName));
+    }
+
+    [Fact]
+    public async Task SearchFiles_WithNullGlobPattern_SearchesAllFilesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "match");
+        await store.WriteFileAsync("folder/data.txt", "match");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "match", filePattern: null);
+
+        // Assert
+        Assert.Equal(2, results.Count);
+    }
+
+    [Fact]
+    public async Task SearchFiles_NoMatch_ReturnsEmptyAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "Some content");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "nonexistent query");
+
+        // Assert
+        Assert.Empty(results);
+    }
+
+    [Fact]
+    public async Task SearchFiles_IgnoresSubdirectoryFilesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+        await store.WriteFileAsync("folder/notes.md", "Match here");
+        await store.WriteFileAsync("folder/sub/deep.md", "Match here too");
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "Match");
+
+        // Assert
+        Assert.Single(results);
+        Assert.Equal("notes.md", results[0].FileName);
+    }
+
+    [Fact]
+    public async Task SearchFiles_Snippet_IncludesSurroundingContextAsync()
+    {
+        // Arrange — place the match in the middle of a long line so ±50 chars are available.
+        var store = new InMemoryAgentFileStore();
+        string padding = new('A', 60);
+        string content = $"{padding}MATCH_HERE{padding}";
+        await store.WriteFileAsync("folder/file.md", content);
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "MATCH_HERE");
+
+        // Assert — snippet should contain the match and surrounding context (up to ±50 chars).
+        Assert.Single(results);
+        string snippet = results[0].Snippet;
+        Assert.Contains("MATCH_HERE", snippet);
+        Assert.True(snippet.Length <= 50 + "MATCH_HERE".Length + 50, "Snippet should be at most ±50 chars around the match.");
+        Assert.True(snippet.Length > "MATCH_HERE".Length, "Snippet should include surrounding context.");
+    }
+
+    [Fact]
+    public async Task SearchFiles_Snippet_MatchNearStartOfFileAsync()
+    {
+        // Arrange — match is at the very beginning, so no leading context is available.
+        var store = new InMemoryAgentFileStore();
+        string trailing = new('B', 80);
+        string content = $"MATCH{trailing}";
+        await store.WriteFileAsync("folder/file.md", content);
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "MATCH");
+
+        // Assert — snippet should start at the beginning of the file.
+        Assert.Single(results);
+        Assert.StartsWith("MATCH", results[0].Snippet);
+        Assert.True(results[0].Snippet.Length <= "MATCH".Length + 50);
+    }
+
+    [Fact]
+    public async Task SearchFiles_Snippet_MatchNearEndOfFileAsync()
+    {
+        // Arrange — match is at the very end, so no trailing context is available.
+        var store = new InMemoryAgentFileStore();
+        string leading = new('C', 80);
+        string content = $"{leading}MATCH";
+        await store.WriteFileAsync("folder/file.md", content);
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "MATCH");
+
+        // Assert — snippet should end at the end of the file.
+        Assert.Single(results);
+        Assert.EndsWith("MATCH", results[0].Snippet);
+        Assert.True(results[0].Snippet.Length <= 50 + "MATCH".Length);
+    }
+
+    [Fact]
+    public async Task SearchFiles_Snippet_UsesFirstMatchPositionAsync()
+    {
+        // Arrange — "target" appears on lines 1 and 3, but the regex only matches line 3
+        // because we require the word "UNIQUE" which only appears on line 3.
+        var store = new InMemoryAgentFileStore();
+        const string Content = "Line one has some text\nLine two is filler\nLine three has UNIQUE_MARKER here";
+        await store.WriteFileAsync("folder/file.md", Content);
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "UNIQUE_MARKER");
+
+        // Assert — snippet should be from around line 3, not line 1.
+        Assert.Single(results);
+        Assert.Contains("UNIQUE_MARKER", results[0].Snippet);
+        Assert.Contains("Line three", results[0].Snippet);
+    }
+
+    [Fact]
+    public async Task SearchFiles_Snippet_CorrectForMultiLineMatchAsync()
+    {
+        // Arrange — match is on the second line with enough distance from line 1
+        // that the ±50 char snippet window does not reach the start of the file.
+        var store = new InMemoryAgentFileStore();
+        string line1 = new('X', 100);
+        string line2 = new string('Y', 60) + "FIND_ME" + new string('Z', 60);
+        string line3 = new('W', 100);
+        string content = $"{line1}\n{line2}\n{line3}";
+        await store.WriteFileAsync("folder/file.md", content);
+
+        // Act
+        var results = await store.SearchFilesAsync("folder", "FIND_ME");
+
+        // Assert — snippet should contain the match from line 2.
+        Assert.Single(results);
+        Assert.Contains("FIND_ME", results[0].Snippet);
+
+        // The match is at offset 101 (line1=100 + '\n') + 60 = 161.
+        // snippetStart = 161 - 50 = 111, which is well past line 1 (ends at offset 100).
+        // So line 1 content should not appear in the snippet.
+        Assert.DoesNotContain("XXXX", results[0].Snippet);
+    }
+
+    [Fact]
+    public async Task PathNormalization_HandlesBackslashesAndTrailingSlashesAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act
+        await store.WriteFileAsync("folder\\file.md", "Content");
+        var content = await store.ReadFileAsync("folder/file.md");
+
+        // Assert
+        Assert.Equal("Content", content);
+    }
+
+    [Fact]
+    public async Task WriteFile_PathTraversal_ThrowsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => store.WriteFileAsync("../escape.md", "Content"));
+    }
+
+    [Fact]
+    public async Task ReadFile_PathTraversal_ThrowsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => store.ReadFileAsync("folder/../../escape.md"));
+    }
+
+    [Fact]
+    public async Task WriteFile_AbsolutePath_ThrowsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => store.WriteFileAsync("/etc/passwd", "Content"));
+    }
+
+    [Fact]
+    public async Task WriteFile_DoubleDotsInFileName_AllowedAsync()
+    {
+        // Arrange — "notes..md" contains ".." as a substring but not as a path segment.
+        var store = new InMemoryAgentFileStore();
+
+        // Act
+        await store.WriteFileAsync("notes..md", "Content");
+        var content = await store.ReadFileAsync("notes..md");
+
+        // Assert
+        Assert.Equal("Content", content);
+    }
+
+    [Fact]
+    public async Task WriteFile_DriveRootedPath_ThrowsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => store.WriteFileAsync("C:\\temp\\file.md", "Content"));
+    }
+
+    [Fact]
+    public async Task ListFiles_PathTraversal_ThrowsAsync()
+    {
+        // Arrange
+        var store = new InMemoryAgentFileStore();
+
+        // Act & Assert
+        await Assert.ThrowsAsync<ArgumentException>(() => store.ListFilesAsync("../other"));
+    }
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/FileStore/StorePathsTests.cs

@@ -0,0 +1,174 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using Microsoft.Extensions.FileSystemGlobbing;
+
+namespace Microsoft.Agents.AI.UnitTests.Harness.FileMemory;
+
+public class StorePathsTests
+{
+    #region NormalizeRelativePath — valid paths
+
+    [Theory]
+    [InlineData("file.md", "file.md")]
+    [InlineData("folder/file.md", "folder/file.md")]
+    [InlineData("a/b/c.txt", "a/b/c.txt")]
+    public void NormalizeRelativePath_ValidPath_ReturnsNormalized(string input, string expected)
+    {
+        // Act
+        string result = StorePaths.NormalizeRelativePath(input);
+
+        // Assert
+        Assert.Equal(expected, result);
+    }
+
+    [Theory]
+    [InlineData("folder\\file.md", "folder/file.md")]
+    [InlineData("a\\b\\c.txt", "a/b/c.txt")]
+    public void NormalizeRelativePath_Backslashes_NormalizesToForwardSlash(string input, string expected)
+    {
+        // Act
+        string result = StorePaths.NormalizeRelativePath(input);
+
+        // Assert
+        Assert.Equal(expected, result);
+    }
+
+    [Theory]
+    [InlineData("folder//file.md", "folder/file.md")]
+    [InlineData("a///b////c.txt", "a/b/c.txt")]
+    public void NormalizeRelativePath_ConsecutiveSeparators_Collapsed(string input, string expected)
+    {
+        // Act
+        string result = StorePaths.NormalizeRelativePath(input);
+
+        // Assert
+        Assert.Equal(expected, result);
+    }
+
+    [Fact]
+    public void NormalizeRelativePath_TrailingSlash_Trimmed()
+    {
+        // Act
+        string result = StorePaths.NormalizeRelativePath("file.md/");
+
+        // Assert
+        Assert.Equal("file.md", result);
+    }
+
+    [Theory]
+    [InlineData("/file.md")]
+    [InlineData("/folder/file.md/")]
+    public void NormalizeRelativePath_LeadingSlash_Throws(string input)
+    {
+        // Act & Assert — leading slash is treated as a rooted path.
+        Assert.Throws<ArgumentException>(() => StorePaths.NormalizeRelativePath(input));
+    }
+
+    #endregion
+
+    #region NormalizeRelativePath — rejected paths
+
+    [Theory]
+    [InlineData("../file.md")]
+    [InlineData("folder/../file.md")]
+    [InlineData("./file.md")]
+    [InlineData("folder/./file.md")]
+    public void NormalizeRelativePath_TraversalSegments_Throws(string input)
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => StorePaths.NormalizeRelativePath(input));
+    }
+
+    [Theory]
+    [InlineData("C:\\file.md")]
+    [InlineData("C:/file.md")]
+    [InlineData("D:file.md")]
+    public void NormalizeRelativePath_DriveRoot_Throws(string input)
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => StorePaths.NormalizeRelativePath(input));
+    }
+
+    [Fact]
+    public void NormalizeRelativePath_EmptyFile_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => StorePaths.NormalizeRelativePath(""));
+    }
+
+    [Fact]
+    public void NormalizeRelativePath_WhitespaceOnlyFile_Throws()
+    {
+        // Act & Assert — whitespace-only paths are rejected as invalid file names.
+        Assert.Throws<ArgumentException>(() => StorePaths.NormalizeRelativePath("   "));
+    }
+
+    #endregion
+
+    #region NormalizeRelativePath — directory mode
+
+    [Fact]
+    public void NormalizeRelativePath_EmptyDirectory_ReturnsEmpty()
+    {
+        // Act
+        string result = StorePaths.NormalizeRelativePath("", isDirectory: true);
+
+        // Assert
+        Assert.Equal("", result);
+    }
+
+    [Theory]
+    [InlineData("folder", "folder")]
+    [InlineData("a/b", "a/b")]
+    [InlineData("a\\b/", "a/b")]
+    public void NormalizeRelativePath_DirectoryMode_NormalizesPath(string input, string expected)
+    {
+        // Act
+        string result = StorePaths.NormalizeRelativePath(input, isDirectory: true);
+
+        // Assert
+        Assert.Equal(expected, result);
+    }
+
+    [Fact]
+    public void NormalizeRelativePath_DirectoryTraversal_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => StorePaths.NormalizeRelativePath("../folder", isDirectory: true));
+    }
+
+    #endregion
+
+    #region CreateGlobMatcher and MatchesGlob
+
+    [Theory]
+    [InlineData("*.md", "notes.md", true)]
+    [InlineData("*.md", "notes.txt", false)]
+    [InlineData("research*", "research_results.md", true)]
+    [InlineData("research*", "notes.md", false)]
+    [InlineData("*.md", "NOTES.MD", true)] // case-insensitive
+    public void MatchesGlob_WithMatcher_MatchesCorrectly(string pattern, string fileName, bool expected)
+    {
+        // Arrange
+        Matcher matcher = StorePaths.CreateGlobMatcher(pattern);
+
+        // Act
+        bool result = StorePaths.MatchesGlob(fileName, matcher);
+
+        // Assert
+        Assert.Equal(expected, result);
+    }
+
+    [Fact]
+    public void MatchesGlob_NullMatcher_ReturnsTrue()
+    {
+        // Act
+        bool result = StorePaths.MatchesGlob("anything.txt", null);
+
+        // Assert
+        Assert.True(result);
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/SubAgents/SubAgentsProviderTests.cs

@@ -0,0 +1,968 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+using System.Threading;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Moq;
+using Moq.Protected;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Unit tests for the <see cref="SubAgentsProvider"/> class.
+/// </summary>
+public class SubAgentsProviderTests
+{
+    #region Constructor Tests
+
+    /// <summary>
+    /// Verify that the constructor throws when agents is null.
+    /// </summary>
+    [Fact]
+    public void Constructor_NullAgents_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>(() => new SubAgentsProvider(null!));
+    }
+
+    /// <summary>
+    /// Verify that the constructor throws when agents collection is empty.
+    /// </summary>
+    [Fact]
+    public void Constructor_EmptyAgents_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(Array.Empty<AIAgent>()));
+    }
+
+    /// <summary>
+    /// Verify that the constructor throws when an agent has a null name.
+    /// </summary>
+    [Fact]
+    public void Constructor_AgentWithNullName_Throws()
+    {
+        // Arrange
+        var agent = CreateMockAgent(null!, "desc");
+
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(new[] { agent }));
+    }
+
+    /// <summary>
+    /// Verify that the constructor throws when an agent has an empty name.
+    /// </summary>
+    [Fact]
+    public void Constructor_AgentWithEmptyName_Throws()
+    {
+        // Arrange
+        var agent = CreateMockAgent("", "desc");
+
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(new[] { agent }));
+    }
+
+    /// <summary>
+    /// Verify that the constructor throws when duplicate agent names are provided (case-insensitive).
+    /// </summary>
+    [Fact]
+    public void Constructor_DuplicateNames_Throws()
+    {
+        // Arrange
+        var agent1 = CreateMockAgent("Research", "Agent 1");
+        var agent2 = CreateMockAgent("research", "Agent 2");
+
+        // Act & Assert
+        Assert.Throws<ArgumentException>(() => new SubAgentsProvider(new[] { agent1, agent2 }));
+    }
+
+    /// <summary>
+    /// Verify that the constructor succeeds with valid agents.
+    /// </summary>
+    [Fact]
+    public void Constructor_ValidAgents_Succeeds()
+    {
+        // Arrange
+        var agent1 = CreateMockAgent("Research", "Research agent");
+        var agent2 = CreateMockAgent("Writer", "Writer agent");
+
+        // Act
+        var provider = new SubAgentsProvider(new[] { agent1, agent2 });
+
+        // Assert
+        Assert.NotNull(provider);
+    }
+
+    #endregion
+
+    #region ProvideAIContextAsync Tests
+
+    /// <summary>
+    /// Verify that the provider returns tools and instructions.
+    /// </summary>
+    [Fact]
+    public async Task ProvideAIContextAsync_ReturnsToolsAndInstructionsAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var provider = new SubAgentsProvider(new[] { agent });
+        var context = CreateInvokingContext();
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.NotNull(result.Instructions);
+        Assert.NotNull(result.Tools);
+        Assert.Equal(6, result.Tools!.Count());
+    }
+
+    /// <summary>
+    /// Verify that the instructions include agent names and descriptions.
+    /// </summary>
+    [Fact]
+    public async Task ProvideAIContextAsync_InstructionsIncludeAgentInfoAsync()
+    {
+        // Arrange
+        var agent1 = CreateMockAgent("Research", "Performs research");
+        var agent2 = CreateMockAgent("Writer", "Writes content");
+        var provider = new SubAgentsProvider(new[] { agent1, agent2 });
+        var context = CreateInvokingContext();
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert — agent info is appended to instructions
+        Assert.Contains("Research", result.Instructions);
+        Assert.Contains("Performs research", result.Instructions);
+        Assert.Contains("Writer", result.Instructions);
+        Assert.Contains("Writes content", result.Instructions);
+    }
+
+    #endregion
+
+    #region StartSubTask Tests
+
+    /// <summary>
+    /// Verify that StartSubTask returns a task ID.
+    /// </summary>
+    [Fact]
+    public async Task StartSubTask_ReturnsTaskIdAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+
+        // Act
+        object? result = await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Find information about AI",
+            ["description"] = "Research AI topics",
+        });
+
+        // Assert
+        string text = GetStringResult(result);
+        Assert.Contains("1", text);
+        Assert.Contains("started", text);
+
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+    }
+
+    /// <summary>
+    /// Verify that StartSubTask with invalid agent name returns an error.
+    /// </summary>
+    [Fact]
+    public async Task StartSubTask_InvalidAgentName_ReturnsErrorAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+
+        // Act
+        object? result = await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "NonExistent",
+            ["input"] = "Some input",
+            ["description"] = "Some task",
+        });
+
+        // Assert
+        string text = GetStringResult(result);
+        Assert.Contains("Error", text);
+        Assert.Contains("NonExistent", text);
+    }
+
+    /// <summary>
+    /// Verify that StartSubTask assigns sequential IDs.
+    /// </summary>
+    [Fact]
+    public async Task StartSubTask_AssignsSequentialIdsAsync()
+    {
+        // Arrange
+        var tcs1 = new TaskCompletionSource<AgentResponse>();
+        var tcs2 = new TaskCompletionSource<AgentResponse>();
+        var callCount = 0;
+        var agent = CreateMockAgentWithCallback("Research", () =>
+        {
+            callCount++;
+            return callCount == 1 ? tcs1.Task : tcs2.Task;
+        });
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+
+        // Act
+        object? result1 = await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Task 1",
+            ["description"] = "First task",
+        });
+        object? result2 = await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Task 2",
+            ["description"] = "Second task",
+        });
+
+        // Assert
+        Assert.Contains("1", GetStringResult(result1));
+        Assert.Contains("2", GetStringResult(result2));
+
+        tcs1.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+        tcs2.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+    }
+
+    #endregion
+
+    #region WaitForFirstCompletion Tests
+
+    /// <summary>
+    /// Verify that WaitForFirstCompletion returns the ID of a completed task.
+    /// </summary>
+    [Fact]
+    public async Task WaitForFirstCompletion_ReturnsCompletedTaskIdAsync()
+    {
+        // Arrange — use a single task to avoid Task.Run scheduling races.
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+
+        // Start one task
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Task 1",
+            ["description"] = "First task",
+        });
+
+        // Complete the task
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "Result 1")));
+
+        // Act
+        object? result = await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int> { 1 },
+        });
+
+        // Assert
+        string text = GetStringResult(result);
+        Assert.Contains("1", text);
+        Assert.Contains("finished with status: Completed", text);
+    }
+
+    /// <summary>
+    /// Verify that WaitForFirstCompletion with empty list returns an error.
+    /// </summary>
+    [Fact]
+    public async Task WaitForFirstCompletion_EmptyList_ReturnsErrorAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+
+        // Act
+        object? result = await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int>(),
+        });
+
+        // Assert
+        Assert.Contains("Error", GetStringResult(result));
+    }
+
+    #endregion
+
+    #region GetSubTaskResults Tests
+
+    /// <summary>
+    /// Verify that GetSubTaskResults returns the result text of a completed task.
+    /// </summary>
+    [Fact]
+    public async Task GetSubTaskResults_CompletedTask_ReturnsResultTextAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+
+        // Start a task
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+
+        // Complete it
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "AI is fascinating!")));
+
+        // Wait for completion to finalize state
+        await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int> { 1 },
+        });
+
+        // Act
+        object? result = await getResults.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+        });
+
+        // Assert
+        Assert.Contains("AI is fascinating!", GetStringResult(result));
+    }
+
+    /// <summary>
+    /// Verify that GetSubTaskResults for a still-running task returns status info.
+    /// </summary>
+    [Fact]
+    public async Task GetSubTaskResults_RunningTask_ReturnsStatusAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+
+        // Start a task (don't complete it)
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+
+        // Act
+        object? result = await getResults.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+        });
+
+        // Assert
+        Assert.Contains("still running", GetStringResult(result));
+
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+    }
+
+    /// <summary>
+    /// Verify that GetSubTaskResults for a nonexistent task returns an error.
+    /// </summary>
+    [Fact]
+    public async Task GetSubTaskResults_NonexistentTask_ReturnsErrorAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+
+        // Act
+        object? result = await getResults.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 999,
+        });
+
+        // Assert
+        Assert.Contains("Error", GetStringResult(result));
+    }
+
+    /// <summary>
+    /// Verify that GetSubTaskResults for a failed task returns the error.
+    /// </summary>
+    [Fact]
+    public async Task GetSubTaskResults_FailedTask_ReturnsErrorTextAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+
+        // Start a task
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+
+        // Fail it
+        tcs.SetException(new InvalidOperationException("Connection failed"));
+
+        // Wait for completion to finalize state
+        await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int> { 1 },
+        });
+
+        // Act
+        object? result = await getResults.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+        });
+
+        // Assert
+        string text = GetStringResult(result);
+        Assert.Contains("failed", text);
+        Assert.Contains("Connection failed", text);
+    }
+
+    #endregion
+
+    #region GetAllTasks Tests
+
+    /// <summary>
+    /// Verify that GetAllTasks returns running tasks with descriptions and status.
+    /// </summary>
+    [Fact]
+    public async Task GetAllTasks_ReturnsRunningTasksAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction getAllTasks = GetTool(tools, "SubAgents_GetAllTasks");
+
+        // Start a task
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research task",
+        });
+
+        // Act
+        object? result = await getAllTasks.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        string text = GetStringResult(result);
+        Assert.Contains("1", text);
+        Assert.Contains("Research", text);
+        Assert.Contains("AI research task", text);
+        Assert.Contains("Running", text);
+
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+    }
+
+    /// <summary>
+    /// Verify that GetAllTasks returns completed tasks with their status.
+    /// </summary>
+    [Fact]
+    public async Task GetAllTasks_ShowsCompletedTasksAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+        AIFunction getAllTasks = GetTool(tools, "SubAgents_GetAllTasks");
+
+        // Start and complete a task
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+        await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int> { 1 },
+        });
+
+        // Act
+        object? result = await getAllTasks.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        string text = GetStringResult(result);
+        Assert.Contains("Completed", text);
+        Assert.Contains("Research", text);
+    }
+
+    /// <summary>
+    /// Verify that GetAllTasks returns no tasks when none exist.
+    /// </summary>
+    [Fact]
+    public async Task GetAllTasks_NoTasks_ReturnsNoneAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction getAllTasks = GetTool(tools, "SubAgents_GetAllTasks");
+
+        // Act
+        object? result = await getAllTasks.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        Assert.Contains("No tasks", GetStringResult(result));
+    }
+
+    #endregion
+
+    #region ContinueTask Tests
+
+    /// <summary>
+    /// Verify that ContinueTask resumes a completed task with new input.
+    /// </summary>
+    [Fact]
+    public async Task ContinueTask_CompletedTask_ResumesAsync()
+    {
+        // Arrange
+        var tcs1 = new TaskCompletionSource<AgentResponse>();
+        var tcs2 = new TaskCompletionSource<AgentResponse>();
+        var callCount = 0;
+        var agent = CreateMockAgentWithCallback("Research", () =>
+        {
+            callCount++;
+            return callCount == 1 ? tcs1.Task : tcs2.Task;
+        });
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+        AIFunction continueTask = GetTool(tools, "SubAgents_ContinueTask");
+        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+
+        // Start and complete a task
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+        tcs1.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "First result")));
+        await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int> { 1 },
+        });
+
+        // Act — continue the task
+        object? continueResult = await continueTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+            ["text"] = "Please elaborate",
+        });
+
+        // Assert — task is resumed
+        Assert.Contains("continued", GetStringResult(continueResult));
+
+        // Complete the second run
+        tcs2.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "Elaborated result")));
+        await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int> { 1 },
+        });
+
+        object? result = await getResults.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+        });
+        Assert.Contains("Elaborated result", GetStringResult(result));
+    }
+
+    /// <summary>
+    /// Verify that ContinueTask on a running task returns an error.
+    /// </summary>
+    [Fact]
+    public async Task ContinueTask_RunningTask_ReturnsErrorAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction continueTask = GetTool(tools, "SubAgents_ContinueTask");
+
+        // Start a task (don't complete it)
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+
+        // Act
+        object? result = await continueTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+            ["text"] = "More input",
+        });
+
+        // Assert
+        Assert.Contains("still running", GetStringResult(result));
+
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+    }
+
+    /// <summary>
+    /// Verify that ContinueTask on a nonexistent task returns an error.
+    /// </summary>
+    [Fact]
+    public async Task ContinueTask_NonexistentTask_ReturnsErrorAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction continueTask = GetTool(tools, "SubAgents_ContinueTask");
+
+        // Act
+        object? result = await continueTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 999,
+            ["text"] = "More input",
+        });
+
+        // Assert
+        Assert.Contains("Error", GetStringResult(result));
+    }
+
+    #endregion
+
+    #region ClearCompletedTask Tests
+
+    /// <summary>
+    /// Verify that ClearCompletedTask removes a terminal task.
+    /// </summary>
+    [Fact]
+    public async Task ClearCompletedTask_RemovesTerminalTaskAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction waitForFirst = GetTool(tools, "SubAgents_WaitForFirstCompletion");
+        AIFunction clearTask = GetTool(tools, "SubAgents_ClearCompletedTask");
+        AIFunction getResults = GetTool(tools, "SubAgents_GetTaskResults");
+
+        // Start and complete a task
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "Result")));
+        await waitForFirst.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskIds"] = new List<int> { 1 },
+        });
+
+        // Act
+        object? clearResult = await clearTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+        });
+
+        // Assert — task is cleared
+        Assert.Contains("cleared", GetStringResult(clearResult));
+
+        // Verify it's gone
+        object? getResult = await getResults.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+        });
+        Assert.Contains("Error", GetStringResult(getResult));
+    }
+
+    /// <summary>
+    /// Verify that ClearCompletedTask on a running task returns an error.
+    /// </summary>
+    [Fact]
+    public async Task ClearCompletedTask_RunningTask_ReturnsErrorAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction startSubTask = GetTool(tools, "SubAgents_StartTask");
+        AIFunction clearTask = GetTool(tools, "SubAgents_ClearCompletedTask");
+
+        // Start a task (don't complete it)
+        await startSubTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Research AI",
+            ["description"] = "AI research",
+        });
+
+        // Act
+        object? result = await clearTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 1,
+        });
+
+        // Assert
+        Assert.Contains("still running", GetStringResult(result));
+
+        tcs.SetResult(new AgentResponse(new ChatMessage(ChatRole.Assistant, "done")));
+    }
+
+    /// <summary>
+    /// Verify that ClearCompletedTask on a nonexistent task returns an error.
+    /// </summary>
+    [Fact]
+    public async Task ClearCompletedTask_NonexistentTask_ReturnsErrorAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        AIFunction clearTask = GetTool(tools, "SubAgents_ClearCompletedTask");
+
+        // Act
+        object? result = await clearTask.InvokeAsync(new AIFunctionArguments
+        {
+            ["taskId"] = 999,
+        });
+
+        // Assert
+        Assert.Contains("Error", GetStringResult(result));
+    }
+
+    #endregion
+
+    #region StateKeys Tests
+
+    /// <summary>
+    /// Verify that the provider exposes state keys.
+    /// </summary>
+    [Fact]
+    public void StateKeys_ReturnsExpectedKeys()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var provider = new SubAgentsProvider(new[] { agent });
+
+        // Act
+        var keys = provider.StateKeys;
+
+        // Assert
+        Assert.NotNull(keys);
+        Assert.Equal(2, keys.Count);
+    }
+
+    #endregion
+
+    #region CurrentRunContext Isolation Tests
+
+    /// <summary>
+    /// Verify that StartSubTask does not corrupt CurrentRunContext of the calling agent.
+    /// Because RunAsync is a non-async method that synchronously sets the static AsyncLocal
+    /// CurrentRunContext, the provider must isolate the sub-agent call to prevent overwriting
+    /// the outer agent's context.
+    /// </summary>
+    [Fact]
+    public async Task StartSubTask_DoesNotCorruptCurrentRunContextAsync()
+    {
+        // Arrange
+        var tcs = new TaskCompletionSource<AgentResponse>();
+        var agent = CreateMockAgentWithRunResult("Research", tcs.Task);
+        var (tools, _) = await CreateToolsWithProviderAsync(agent);
+        var startTool = GetTool(tools, "SubAgents_StartTask");
+
+        AgentRunContext? contextBefore = AIAgent.CurrentRunContext;
+
+        // Act — invoke StartSubTask; this calls agent.RunAsync internally.
+        var args = new AIFunctionArguments(new Dictionary<string, object?>
+        {
+            ["agentName"] = "Research",
+            ["input"] = "Do work",
+            ["description"] = "test task",
+        });
+        await startTool.InvokeAsync(args);
+
+        // Assert — CurrentRunContext should be unchanged.
+        Assert.Equal(contextBefore, AIAgent.CurrentRunContext);
+
+        // Clean up
+        tcs.SetResult(new AgentResponse(new List<ChatMessage> { new(ChatRole.Assistant, "done") }));
+    }
+
+    #endregion
+
+    #region Options Tests
+
+    /// <summary>
+    /// Verify that custom instructions from options override the default instructions but agent list is still injected via placeholder.
+    /// </summary>
+    [Fact]
+    public async Task CustomInstructions_OverridesDefaultInstructionsAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        const string CustomInstructions = "These are custom sub-agent instructions.\n{sub_agents}";
+        var options = new SubAgentsProviderOptions { Instructions = CustomInstructions };
+        var provider = new SubAgentsProvider(new[] { agent }, options);
+        var context = CreateInvokingContext();
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert — custom instructions replace default, agent list is injected via {sub_agents} placeholder
+        Assert.Contains("These are custom sub-agent instructions.", result.Instructions);
+        Assert.Contains("Research", result.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that default instructions contain tool reference and agent names.
+    /// </summary>
+    [Fact]
+    public async Task DefaultInstructions_ContainsToolReferenceAndAgentListAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var provider = new SubAgentsProvider(new[] { agent });
+        var context = CreateInvokingContext();
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert — instructions contain tool usage guidance and agent list
+        Assert.Contains("SubAgents_*", result.Instructions);
+        Assert.Contains("SubAgents_ClearCompletedTask", result.Instructions);
+        Assert.Contains("Research", result.Instructions);
+        Assert.Contains("Research agent", result.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that a custom AgentListBuilder function is used to build the agent list text.
+    /// </summary>
+    [Fact]
+    public async Task CustomAgentListBuilder_UsedForAgentListAsync()
+    {
+        // Arrange
+        var agent = CreateMockAgent("Research", "Research agent");
+        var options = new SubAgentsProviderOptions
+        {
+            AgentListBuilder = agents => $"Custom list: {string.Join(", ", agents.Keys)}",
+        };
+        var provider = new SubAgentsProvider(new[] { agent }, options);
+        var context = CreateInvokingContext();
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert — custom agent list builder output is in instructions
+        Assert.Contains("Custom list: Research", result.Instructions);
+        Assert.DoesNotContain("Available sub-agents:", result.Instructions);
+    }
+
+    #endregion
+
+    #region Helper Methods
+
+    private static AIAgent CreateMockAgent(string? name, string? description)
+    {
+        var mock = new Mock<AIAgent>();
+        mock.SetupGet(a => a.Name).Returns(name!);
+        mock.SetupGet(a => a.Description).Returns(description);
+        return mock.Object;
+    }
+
+    private static AIAgent CreateMockAgentWithRunResult(string name, Task<AgentResponse> result)
+    {
+        var mock = new Mock<AIAgent>();
+        mock.SetupGet(a => a.Name).Returns(name);
+        mock.Protected()
+            .Setup<ValueTask<AgentSession>>(
+                "CreateSessionCoreAsync",
+                ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask<AgentSession>(new ChatClientAgentSession()));
+        mock.Protected()
+            .Setup<Task<AgentResponse>>(
+                "RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession>(),
+                ItExpr.IsAny<AgentRunOptions>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Returns(result);
+        return mock.Object;
+    }
+
+    private static AIAgent CreateMockAgentWithCallback(string name, Func<Task<AgentResponse>> callback)
+    {
+        var mock = new Mock<AIAgent>();
+        mock.SetupGet(a => a.Name).Returns(name);
+        mock.Protected()
+            .Setup<ValueTask<AgentSession>>(
+                "CreateSessionCoreAsync",
+                ItExpr.IsAny<CancellationToken>())
+            .Returns(new ValueTask<AgentSession>(new ChatClientAgentSession()));
+        mock.Protected()
+            .Setup<Task<AgentResponse>>(
+                "RunCoreAsync",
+                ItExpr.IsAny<IEnumerable<ChatMessage>>(),
+                ItExpr.IsAny<AgentSession>(),
+                ItExpr.IsAny<AgentRunOptions>(),
+                ItExpr.IsAny<CancellationToken>())
+            .Returns(callback);
+        return mock.Object;
+    }
+
+    private static async Task<(IEnumerable<AITool> Tools, SubAgentsProvider Provider)> CreateToolsWithProviderAsync(AIAgent agent)
+    {
+        var provider = new SubAgentsProvider(new[] { agent });
+        var context = CreateInvokingContext();
+
+        AIContext result = await provider.InvokingAsync(context);
+        return (result.Tools!, provider);
+    }
+
+    private static AIContextProvider.InvokingContext CreateInvokingContext()
+    {
+        var mockAgent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        return new AIContextProvider.InvokingContext(mockAgent, session, new AIContext());
+#pragma warning restore MAAI001
+    }
+
+    private static AIFunction GetTool(IEnumerable<AITool> tools, string name)
+    {
+        return (AIFunction)tools.First(t => t is AIFunction f && f.Name == name);
+    }
+
+    private static string GetStringResult(object? result)
+    {
+        var element = Assert.IsType<JsonElement>(result);
+        return element.GetString()!;
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/Todo/TodoProviderTests.cs

@@ -0,0 +1,492 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json;
+using System.Threading.Tasks;
+using Microsoft.Extensions.AI;
+using Moq;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Unit tests for the <see cref="TodoProvider"/> class.
+/// </summary>
+public class TodoProviderTests
+{
+    #region ProvideAIContextAsync Tests
+
+    /// <summary>
+    /// Verify that the provider returns tools and instructions.
+    /// </summary>
+    [Fact]
+    public async Task ProvideAIContextAsync_ReturnsToolsAndInstructionsAsync()
+    {
+        // Arrange
+        var provider = new TodoProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.NotNull(result.Instructions);
+        Assert.NotNull(result.Tools);
+        Assert.Equal(5, result.Tools!.Count());
+    }
+
+    #endregion
+
+    #region AddTodos Tests
+
+    /// <summary>
+    /// Verify that AddTodos creates a new todo item when given a single item.
+    /// </summary>
+    [Fact]
+    public async Task AddTodos_CreatesSingleItemAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+
+        // Act
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput> { new() { Title = "Test todo", Description = "A test description" } },
+        });
+
+        // Assert
+        Assert.Single(state.Items);
+        Assert.Equal("Test todo", state.Items[0].Title);
+        Assert.Equal("A test description", state.Items[0].Description);
+        Assert.False(state.Items[0].IsComplete);
+        Assert.Equal(1, state.Items[0].Id);
+    }
+
+    /// <summary>
+    /// Verify that AddTodos creates multiple items with incrementing IDs.
+    /// </summary>
+    [Fact]
+    public async Task AddTodos_CreatesMultipleItemsWithIncrementingIdsAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+
+        // Act
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput>
+            {
+                new() { Title = "First", Description = null },
+                new() { Title = "Second", Description = null },
+                new() { Title = "Third", Description = "With description" },
+            },
+        });
+
+        // Assert
+        Assert.Equal(3, state.Items.Count);
+        Assert.Equal(1, state.Items[0].Id);
+        Assert.Equal("First", state.Items[0].Title);
+        Assert.Equal(2, state.Items[1].Id);
+        Assert.Equal("Second", state.Items[1].Title);
+        Assert.Equal(3, state.Items[2].Id);
+        Assert.Equal("Third", state.Items[2].Title);
+        Assert.Equal("With description", state.Items[2].Description);
+    }
+
+    #endregion
+
+    #region CompleteTodos Tests
+
+    /// <summary>
+    /// Verify that CompleteTodos marks an item as complete.
+    /// </summary>
+    [Fact]
+    public async Task CompleteTodos_MarksItemCompleteAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+        AIFunction completeTodos = GetTool(tools, "TodoList_Complete");
+        await addTodos.InvokeAsync(new AIFunctionArguments() { ["todos"] = new List<TodoItemInput> { new() { Title = "Test", Description = null } } });
+
+        // Act
+        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+
+        // Assert
+        Assert.True(state.Items[0].IsComplete);
+        Assert.Equal(1, GetIntResult(result));
+    }
+
+    /// <summary>
+    /// Verify that CompleteTodos marks multiple items as complete.
+    /// </summary>
+    [Fact]
+    public async Task CompleteTodos_MarksMultipleItemsCompleteAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+        AIFunction completeTodos = GetTool(tools, "TodoList_Complete");
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput> { new() { Title = "First" }, new() { Title = "Second" }, new() { Title = "Third" } },
+        });
+
+        // Act
+        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1, 3 } });
+
+        // Assert
+        Assert.True(state.Items[0].IsComplete);
+        Assert.False(state.Items[1].IsComplete);
+        Assert.True(state.Items[2].IsComplete);
+        Assert.Equal(2, GetIntResult(result));
+    }
+
+    /// <summary>
+    /// Verify that CompleteTodos returns zero for non-existent IDs.
+    /// </summary>
+    [Fact]
+    public async Task CompleteTodos_ReturnsZeroForMissingIdsAsync()
+    {
+        // Arrange
+        var (tools, _) = await CreateToolsWithStateAsync();
+        AIFunction completeTodos = GetTool(tools, "TodoList_Complete");
+
+        // Act
+        object? result = await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 999 } });
+
+        // Assert
+        Assert.Equal(0, GetIntResult(result));
+    }
+
+    #endregion
+
+    #region RemoveTodos Tests
+
+    /// <summary>
+    /// Verify that RemoveTodos removes an item.
+    /// </summary>
+    [Fact]
+    public async Task RemoveTodos_RemovesItemAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+        AIFunction removeTodos = GetTool(tools, "TodoList_Remove");
+        await addTodos.InvokeAsync(new AIFunctionArguments() { ["todos"] = new List<TodoItemInput> { new() { Title = "Test", Description = null } } });
+
+        // Act
+        object? result = await removeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+
+        // Assert
+        Assert.Empty(state.Items);
+        Assert.Equal(1, GetIntResult(result));
+    }
+
+    /// <summary>
+    /// Verify that RemoveTodos removes multiple items.
+    /// </summary>
+    [Fact]
+    public async Task RemoveTodos_RemovesMultipleItemsAsync()
+    {
+        // Arrange
+        var (tools, state) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+        AIFunction removeTodos = GetTool(tools, "TodoList_Remove");
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput> { new() { Title = "First" }, new() { Title = "Second" }, new() { Title = "Third" } },
+        });
+
+        // Act
+        object? result = await removeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1, 3 } });
+
+        // Assert
+        Assert.Single(state.Items);
+        Assert.Equal("Second", state.Items[0].Title);
+        Assert.Equal(2, GetIntResult(result));
+    }
+
+    /// <summary>
+    /// Verify that RemoveTodos returns zero for non-existent IDs.
+    /// </summary>
+    [Fact]
+    public async Task RemoveTodos_ReturnsZeroForMissingIdsAsync()
+    {
+        // Arrange
+        var (tools, _) = await CreateToolsWithStateAsync();
+        AIFunction removeTodos = GetTool(tools, "TodoList_Remove");
+
+        // Act
+        object? result = await removeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 999 } });
+
+        // Assert
+        Assert.Equal(0, GetIntResult(result));
+    }
+
+    #endregion
+
+    #region GetRemainingTodos Tests
+
+    /// <summary>
+    /// Verify that GetRemainingTodos returns only incomplete items.
+    /// </summary>
+    [Fact]
+    public async Task GetRemainingTodos_ReturnsOnlyIncompleteAsync()
+    {
+        // Arrange
+        var (tools, _) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+        AIFunction completeTodos = GetTool(tools, "TodoList_Complete");
+        AIFunction getRemainingTodos = GetTool(tools, "TodoList_GetRemaining");
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput> { new() { Title = "Done", Description = null }, new() { Title = "Pending", Description = null } },
+        });
+        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+
+        // Act
+        object? result = await getRemainingTodos.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        var remaining = GetArrayResult(result);
+        Assert.Single(remaining);
+        Assert.Equal("Pending", remaining[0].GetProperty("title").GetString());
+    }
+
+    #endregion
+
+    #region GetAllTodos Tests
+
+    /// <summary>
+    /// Verify that GetAllTodos returns all items.
+    /// </summary>
+    [Fact]
+    public async Task GetAllTodos_ReturnsAllItemsAsync()
+    {
+        // Arrange
+        var (tools, _) = await CreateToolsWithStateAsync();
+        AIFunction addTodos = GetTool(tools, "TodoList_Add");
+        AIFunction completeTodos = GetTool(tools, "TodoList_Complete");
+        AIFunction getAllTodos = GetTool(tools, "TodoList_GetAll");
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput> { new() { Title = "Done", Description = null }, new() { Title = "Pending", Description = null } },
+        });
+        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+
+        // Act
+        object? result = await getAllTodos.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        var all = GetArrayResult(result);
+        Assert.Equal(2, all.Count);
+    }
+
+    #endregion
+
+    #region State Persistence Tests
+
+    /// <summary>
+    /// Verify that state persists in the session StateBag.
+    /// </summary>
+    [Fact]
+    public async Task State_PersistsInSessionStateBagAsync()
+    {
+        // Arrange
+        var provider = new TodoProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act — first invocation adds a todo
+        AIContext result1 = await provider.InvokingAsync(context);
+        AIFunction addTodos = (AIFunction)result1.Tools!.First(t => t is AIFunction f && f.Name == "TodoList_Add");
+        await addTodos.InvokeAsync(new AIFunctionArguments() { ["todos"] = new List<TodoItemInput> { new() { Title = "Persisted", Description = null } } });
+
+        // Second invocation should see the same state
+        AIContext result2 = await provider.InvokingAsync(context);
+        AIFunction getAllTodos = (AIFunction)result2.Tools!.First(t => t is AIFunction f && f.Name == "TodoList_GetAll");
+        object? allResult = await getAllTodos.InvokeAsync(new AIFunctionArguments());
+
+        // Assert
+        var all = GetArrayResult(allResult);
+        Assert.Single(all);
+        Assert.Equal("Persisted", all[0].GetProperty("title").GetString());
+    }
+
+    #endregion
+
+    #region Public Helper Method Tests
+
+    /// <summary>
+    /// Verify that GetAllTodos returns all items after adding via tools.
+    /// </summary>
+    [Fact]
+    public async Task PublicGetAllTodos_ReturnsAllItemsAsync()
+    {
+        // Arrange
+        var provider = new TodoProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+        AIContext result = await provider.InvokingAsync(context);
+        AIFunction addTodos = GetTool(result.Tools!, "TodoList_Add");
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput> { new() { Title = "First", Description = null }, new() { Title = "Second", Description = null } },
+        });
+
+        // Act
+        var todos = provider.GetAllTodos(session);
+
+        // Assert
+        Assert.Equal(2, todos.Count);
+        Assert.Equal("First", todos[0].Title);
+        Assert.Equal("Second", todos[1].Title);
+    }
+
+    /// <summary>
+    /// Verify that GetRemainingTodos returns only incomplete items.
+    /// </summary>
+    [Fact]
+    public async Task PublicGetRemainingTodos_ReturnsOnlyIncompleteAsync()
+    {
+        // Arrange
+        var provider = new TodoProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+        AIContext result = await provider.InvokingAsync(context);
+        AIFunction addTodos = GetTool(result.Tools!, "TodoList_Add");
+        AIFunction completeTodos = GetTool(result.Tools!, "TodoList_Complete");
+        await addTodos.InvokeAsync(new AIFunctionArguments()
+        {
+            ["todos"] = new List<TodoItemInput> { new() { Title = "Done", Description = null }, new() { Title = "Pending", Description = null } },
+        });
+        await completeTodos.InvokeAsync(new AIFunctionArguments() { ["ids"] = new List<int> { 1 } });
+
+        // Act
+        var remaining = provider.GetRemainingTodos(session);
+
+        // Assert
+        Assert.Single(remaining);
+        Assert.Equal("Pending", remaining[0].Title);
+    }
+
+    /// <summary>
+    /// Verify that GetAllTodos returns empty list for a new session.
+    /// </summary>
+    [Fact]
+    public void PublicGetAllTodos_ReturnsEmptyForNewSession()
+    {
+        // Arrange
+        var provider = new TodoProvider();
+        var session = new ChatClientAgentSession();
+
+        // Act
+        var todos = provider.GetAllTodos(session);
+
+        // Assert
+        Assert.Empty(todos);
+    }
+
+    #endregion
+
+    #region Helper Methods
+
+    private static async Task<(IEnumerable<AITool> Tools, TodoState State)> CreateToolsWithStateAsync()
+    {
+        var provider = new TodoProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Retrieve the state from the session to verify mutations
+        session.StateBag.TryGetValue<TodoState>("TodoProvider", out var state, AgentJsonUtilities.DefaultOptions);
+
+        return (result.Tools!, state!);
+    }
+
+    private static AIFunction GetTool(IEnumerable<AITool> tools, string name)
+    {
+        return (AIFunction)tools.First(t => t is AIFunction f && f.Name == name);
+    }
+
+    private static int GetIntResult(object? result)
+    {
+        var element = Assert.IsType<JsonElement>(result);
+        return element.GetInt32();
+    }
+
+    private static List<JsonElement> GetArrayResult(object? result)
+    {
+        var element = Assert.IsType<JsonElement>(result);
+        return element.EnumerateArray().ToList();
+    }
+
+    #endregion
+
+    #region Options Tests
+
+    /// <summary>
+    /// Verify that custom instructions override the default.
+    /// </summary>
+    [Fact]
+    public async Task Options_CustomInstructions_OverridesDefaultAsync()
+    {
+        // Arrange
+        var options = new TodoProviderOptions { Instructions = "Custom todo instructions." };
+        var provider = new TodoProvider(options);
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Equal("Custom todo instructions.", result.Instructions);
+    }
+
+    /// <summary>
+    /// Verify that null options uses default instructions.
+    /// </summary>
+    [Fact]
+    public async Task Options_Null_UsesDefaultInstructionsAsync()
+    {
+        // Arrange
+        var provider = new TodoProvider();
+        var agent = new Mock<AIAgent>().Object;
+        var session = new ChatClientAgentSession();
+#pragma warning disable MAAI001
+        var context = new AIContextProvider.InvokingContext(agent, session, new AIContext());
+#pragma warning restore MAAI001
+
+        // Act
+        AIContext result = await provider.InvokingAsync(context);
+
+        // Assert
+        Assert.Contains("todo list", result.Instructions);
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/ToolApproval/AlwaysApproveToolApprovalResponseContentTests.cs

@@ -0,0 +1,288 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Collections.Generic;
+using Microsoft.Extensions.AI;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Unit tests for the <see cref="AlwaysApproveToolApprovalResponseContent"/> class
+/// and <see cref="ToolApprovalRequestContentExtensions"/> extension methods.
+/// </summary>
+public class AlwaysApproveToolApprovalResponseContentTests
+{
+    #region CreateAlwaysApproveToolResponse
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse sets AlwaysApproveTool to true.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_AlwaysApproveTool_IsTrue()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse();
+
+        // Assert
+        Assert.True(result.AlwaysApproveTool);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse sets AlwaysApproveToolWithArguments to false.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_AlwaysApproveToolWithArguments_IsFalse()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse();
+
+        // Assert
+        Assert.False(result.AlwaysApproveToolWithArguments);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse creates an approved inner response.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_InnerResponse_IsApproved()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse();
+
+        // Assert
+        Assert.True(result.InnerResponse.Approved);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse forwards the reason.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_Reason_IsForwarded()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse("User trusts this tool");
+
+        // Assert
+        Assert.Equal("User trusts this tool", result.InnerResponse.Reason);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse preserves the request ID.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_RequestId_IsPreserved()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool", "custom-request-id");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse();
+
+        // Assert
+        Assert.Equal("custom-request-id", result.InnerResponse.RequestId);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse preserves the tool call.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_ToolCall_IsPreserved()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse();
+
+        // Assert
+        var functionCall = Assert.IsType<FunctionCallContent>(result.InnerResponse.ToolCall);
+        Assert.Equal("MyTool", functionCall.Name);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse with null reason sets reason to null.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_NullReason_ReasonIsNull()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse();
+
+        // Assert
+        Assert.Null(result.InnerResponse.Reason);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolResponse throws on null request.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolResponse_NullRequest_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>("request",
+            () => ((ToolApprovalRequestContent)null!).CreateAlwaysApproveToolResponse());
+    }
+
+    #endregion
+
+    #region CreateAlwaysApproveToolWithArgumentsResponse
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolWithArgumentsResponse sets AlwaysApproveToolWithArguments to true.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolWithArgumentsResponse_AlwaysApproveToolWithArguments_IsTrue()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolWithArgumentsResponse();
+
+        // Assert
+        Assert.True(result.AlwaysApproveToolWithArguments);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolWithArgumentsResponse sets AlwaysApproveTool to false.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolWithArgumentsResponse_AlwaysApproveTool_IsFalse()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolWithArgumentsResponse();
+
+        // Assert
+        Assert.False(result.AlwaysApproveTool);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolWithArgumentsResponse creates an approved inner response.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolWithArgumentsResponse_InnerResponse_IsApproved()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolWithArgumentsResponse();
+
+        // Assert
+        Assert.True(result.InnerResponse.Approved);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolWithArgumentsResponse forwards the reason.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolWithArgumentsResponse_Reason_IsForwarded()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolWithArgumentsResponse("Specific approval");
+
+        // Assert
+        Assert.Equal("Specific approval", result.InnerResponse.Reason);
+    }
+
+    /// <summary>
+    /// Verify that CreateAlwaysApproveToolWithArgumentsResponse throws on null request.
+    /// </summary>
+    [Fact]
+    public void CreateAlwaysApproveToolWithArgumentsResponse_NullRequest_Throws()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>("request",
+            () => ((ToolApprovalRequestContent)null!).CreateAlwaysApproveToolWithArgumentsResponse());
+    }
+
+    #endregion
+
+    #region AlwaysApproveToolApprovalResponseContent Properties
+
+    /// <summary>
+    /// Verify that the content is an AIContent subclass.
+    /// </summary>
+    [Fact]
+    public void Content_IsAIContentSubclass()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var result = request.CreateAlwaysApproveToolResponse();
+
+        // Assert
+        Assert.IsAssignableFrom<AIContent>(result);
+    }
+
+    /// <summary>
+    /// Verify that InnerResponse preserves tool call arguments.
+    /// </summary>
+    [Fact]
+    public void InnerResponse_PreservesArguments()
+    {
+        // Arrange
+        var args = new Dictionary<string, object?> { ["path"] = "test.txt", ["count"] = 5 };
+        var request = new ToolApprovalRequestContent("req1",
+            new FunctionCallContent("call1", "ReadFile", args));
+
+        // Act
+        var result = request.CreateAlwaysApproveToolWithArgumentsResponse();
+
+        // Assert
+        var functionCall = Assert.IsType<FunctionCallContent>(result.InnerResponse.ToolCall);
+        Assert.Equal(2, functionCall.Arguments!.Count);
+        Assert.Equal("test.txt", functionCall.Arguments["path"]);
+    }
+
+    /// <summary>
+    /// Verify that both factory methods produce distinct instances from the same request.
+    /// </summary>
+    [Fact]
+    public void FactoryMethods_ProduceDistinctInstances()
+    {
+        // Arrange
+        var request = CreateRequest("MyTool");
+
+        // Act
+        var toolLevel = request.CreateAlwaysApproveToolResponse();
+        var argsLevel = request.CreateAlwaysApproveToolWithArgumentsResponse();
+
+        // Assert
+        Assert.NotSame(toolLevel, argsLevel);
+        Assert.NotSame(toolLevel.InnerResponse, argsLevel.InnerResponse);
+    }
+
+    #endregion
+
+    #region Helpers
+
+    private static ToolApprovalRequestContent CreateRequest(string toolName, string requestId = "req1")
+    {
+        return new ToolApprovalRequestContent(requestId, new FunctionCallContent("call1", toolName));
+    }
+
+    #endregion
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/ToolApproval/ToolApprovalAgentBuilderExtensionsTests.cs

@@ -0,0 +1,75 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Text.Json;
+using Moq;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Unit tests for the <see cref="ToolApprovalAgentBuilderExtensions"/> class.
+/// </summary>
+public class ToolApprovalAgentBuilderExtensionsTests
+{
+    /// <summary>
+    /// Verify that UseToolApproval throws ArgumentNullException when builder is null.
+    /// </summary>
+    [Fact]
+    public void UseToolApproval_WithNullBuilder_ThrowsArgumentNullException()
+    {
+        // Act & Assert
+        Assert.Throws<ArgumentNullException>("builder", () => ((AIAgentBuilder)null!).UseToolApproval());
+    }
+
+    /// <summary>
+    /// Verify that UseToolApproval returns a ToolApprovalAgent.
+    /// </summary>
+    [Fact]
+    public void UseToolApproval_WithValidBuilder_ReturnsToolApprovalAgent()
+    {
+        // Arrange
+        var mockAgent = new Mock<AIAgent>();
+        var builder = new AIAgentBuilder(mockAgent.Object);
+
+        // Act
+        var result = builder.UseToolApproval().Build();
+
+        // Assert
+        Assert.IsType<ToolApprovalAgent>(result);
+    }
+
+    /// <summary>
+    /// Verify that UseToolApproval returns the same builder instance for chaining.
+    /// </summary>
+    [Fact]
+    public void UseToolApproval_ReturnsBuilderForChaining()
+    {
+        // Arrange
+        var mockAgent = new Mock<AIAgent>();
+        var builder = new AIAgentBuilder(mockAgent.Object);
+
+        // Act
+        var result = builder.UseToolApproval();
+
+        // Assert
+        Assert.Same(builder, result);
+    }
+
+    /// <summary>
+    /// Verify that UseToolApproval with custom JsonSerializerOptions works correctly.
+    /// </summary>
+    [Fact]
+    public void UseToolApproval_WithCustomJsonSerializerOptions_ReturnsToolApprovalAgent()
+    {
+        // Arrange
+        var mockAgent = new Mock<AIAgent>();
+        var builder = new AIAgentBuilder(mockAgent.Object);
+        var options = new JsonSerializerOptions();
+
+        // Act
+        var result = builder.UseToolApproval(jsonSerializerOptions: options).Build();
+
+        // Assert
+        Assert.IsType<ToolApprovalAgent>(result);
+    }
+}

dotnet/tests/Microsoft.Agents.AI.UnitTests/Harness/ToolApproval/ToolApprovalRuleTests.cs

@@ -0,0 +1,154 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System.Collections.Generic;
+using System.Text.Json;
+
+namespace Microsoft.Agents.AI.UnitTests;
+
+/// <summary>
+/// Unit tests for the <see cref="ToolApprovalRule"/> class.
+/// </summary>
+public class ToolApprovalRuleTests
+{
+    #region Construction and Defaults
+
+    /// <summary>
+    /// Verify that a new rule has the expected default values.
+    /// </summary>
+    [Fact]
+    public void NewRule_HasDefaultValues()
+    {
+        // Act
+        var rule = new ToolApprovalRule();
+
+        // Assert
+        Assert.Equal(string.Empty, rule.ToolName);
+        Assert.Null(rule.Arguments);
+    }
+
+    /// <summary>
+    /// Verify that ToolName can be set.
+    /// </summary>
+    [Fact]
+    public void ToolName_CanBeSet()
+    {
+        // Arrange & Act
+        var rule = new ToolApprovalRule { ToolName = "ReadFile" };
+
+        // Assert
+        Assert.Equal("ReadFile", rule.ToolName);
+    }
+
+    /// <summary>
+    /// Verify that Arguments can be set.
+    /// </summary>
+    [Fact]
+    public void Arguments_CanBeSet()
+    {
+        // Arrange & Act
+        var args = new Dictionary<string, string> { ["path"] = "test.txt" };
+        var rule = new ToolApprovalRule { ToolName = "ReadFile", Arguments = args };
+
+        // Assert
+        Assert.NotNull(rule.Arguments);
+        Assert.Equal("test.txt", rule.Arguments["path"]);
+    }
+
+    #endregion
+
+    #region JSON Serialization
+
+    /// <summary>
+    /// Verify that a tool-level rule round-trips through JSON serialization.
+    /// </summary>
+    [Fact]
+    public void Serialize_ToolLevelRule_RoundTrips()
+    {
+        // Arrange
+        var rule = new ToolApprovalRule { ToolName = "MyTool" };
+
+        // Act
+        var json = JsonSerializer.Serialize(rule, AgentJsonUtilities.DefaultOptions);
+        var deserialized = JsonSerializer.Deserialize<ToolApprovalRule>(json, AgentJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(deserialized);
+        Assert.Equal("MyTool", deserialized!.ToolName);
+        Assert.Null(deserialized.Arguments);
+    }
+
+    /// <summary>
+    /// Verify that a tool+arguments rule round-trips through JSON serialization.
+    /// </summary>
+    [Fact]
+    public void Serialize_ToolWithArgsRule_RoundTrips()
+    {
+        // Arrange
+        var rule = new ToolApprovalRule
+        {
+            ToolName = "ReadFile",
+            Arguments = new Dictionary<string, string> { ["path"] = "test.txt", ["encoding"] = "utf-8" },
+        };
+
+        // Act
+        var json = JsonSerializer.Serialize(rule, AgentJsonUtilities.DefaultOptions);
+        var deserialized = JsonSerializer.Deserialize<ToolApprovalRule>(json, AgentJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(deserialized);
+        Assert.Equal("ReadFile", deserialized!.ToolName);
+        Assert.NotNull(deserialized.Arguments);
+        Assert.Equal(2, deserialized.Arguments!.Count);
+        Assert.Equal("test.txt", deserialized.Arguments["path"]);
+        Assert.Equal("utf-8", deserialized.Arguments["encoding"]);
+    }
+
+    /// <summary>
+    /// Verify that JSON property names are correctly applied.
+    /// </summary>
+    [Fact]
+    public void Serialize_UsesJsonPropertyNames()
+    {
+        // Arrange
+        var rule = new ToolApprovalRule
+        {
+            ToolName = "MyTool",
+            Arguments = new Dictionary<string, string> { ["key"] = "value" },
+        };
+
+        // Act
+        var json = JsonSerializer.Serialize(rule, AgentJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.Contains("\"toolName\"", json);
+        Assert.Contains("\"arguments\"", json);
+    }
+
+    /// <summary>
+    /// Verify that a list of rules round-trips through JSON serialization.
+    /// </summary>
+    [Fact]
+    public void Serialize_RuleList_RoundTrips()
+    {
+        // Arrange
+        var rules = new List<ToolApprovalRule>
+        {
+            new() { ToolName = "ToolA" },
+            new() { ToolName = "ToolB", Arguments = new Dictionary<string, string> { ["x"] = "1" } },
+        };
+
+        // Act
+        var json = JsonSerializer.Serialize(rules, AgentJsonUtilities.DefaultOptions);
+        var deserialized = JsonSerializer.Deserialize<List<ToolApprovalRule>>(json, AgentJsonUtilities.DefaultOptions);
+
+        // Assert
+        Assert.NotNull(deserialized);
+        Assert.Equal(2, deserialized!.Count);
+        Assert.Equal("ToolA", deserialized[0].ToolName);
+        Assert.Null(deserialized[0].Arguments);
+        Assert.Equal("ToolB", deserialized[1].ToolName);
+        Assert.NotNull(deserialized[1].Arguments);
+    }
+
+    #endregion
+}