.NET: Feat/dotnet shell tool

dotnet/agent-framework-dotnet.slnx

@@ -556,6 +556,7 @@
     <Project Path="src/Microsoft.Agents.AI.Mem0/Microsoft.Agents.AI.Mem0.csproj" />
     <Project Path="src/Microsoft.Agents.AI.OpenAI/Microsoft.Agents.AI.OpenAI.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Purview/Microsoft.Agents.AI.Purview.csproj" />
+    <Project Path="src/Microsoft.Agents.AI.Tools.Shell/Microsoft.Agents.AI.Tools.Shell.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Foundry/Microsoft.Agents.AI.Workflows.Declarative.Foundry.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative.Mcp/Microsoft.Agents.AI.Workflows.Declarative.Mcp.csproj" />
     <Project Path="src/Microsoft.Agents.AI.Workflows.Declarative/Microsoft.Agents.AI.Workflows.Declarative.csproj" />
@@ -601,6 +602,7 @@
     <Project Path="tests/Microsoft.Agents.AI.Mem0.UnitTests/Microsoft.Agents.AI.Mem0.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.OpenAI.UnitTests/Microsoft.Agents.AI.OpenAI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Purview.UnitTests/Microsoft.Agents.AI.Purview.UnitTests.csproj" />
+    <Project Path="tests/Microsoft.Agents.AI.Tools.Shell.UnitTests/Microsoft.Agents.AI.Tools.Shell.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.UnitTests/Microsoft.Agents.AI.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.Mcp.UnitTests.csproj" />
     <Project Path="tests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests/Microsoft.Agents.AI.Workflows.Declarative.UnitTests.csproj" />

dotnet/src/Microsoft.Agents.AI.Tools.Shell/IShellExecutor.cs

@@ -0,0 +1,53 @@
+// Copyright (c) Microsoft. All rights reserved.
+
+using System;
+using System.Threading;
+using System.Threading.Tasks;
+
+namespace Microsoft.Agents.AI.Tools.Shell;
+
+/// <summary>
+/// Pluggable backend that runs shell commands on behalf of a tool.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <see cref="LocalShellTool"/> runs commands directly on the host (no
+/// isolation; approval-in-the-loop is the security boundary). A future
+/// <c>DockerShellTool</c> runs them inside a container with resource
+/// limits, network isolation, and a non-root user — the container itself
+/// is the security boundary, which is why it can be used without approval
+/// gating for untrusted-input scenarios.
+/// </para>
+/// <para>
+/// The interface is intentionally minimal so callers can plug in their own
+/// executor (Firecracker microVM, remote SSH, WASI runtime, etc.) without
+/// forking the framework. Mirrors the Python <c>ShellExecutor</c> Protocol
+/// in <c>agent_framework_tools.shell._executor_base</c>.
+/// </para>
+/// </remarks>
+public interface IShellExecutor : IAsyncDisposable
+{
+    /// <summary>
+    /// Eagerly initialize the backend. Idempotent; subsequent calls are
+    /// no-ops once the executor is started. For stateless executors this
+    /// is typically a no-op.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task StartAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Tear down all backend resources. Idempotent; safe to call multiple
+    /// times.
+    /// </summary>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task CloseAsync(CancellationToken cancellationToken = default);
+
+    /// <summary>
+    /// Run a single command and return its result. Implementations are
+    /// expected to apply the configured per-command timeout and surface
+    /// it via <see cref="ShellResult.TimedOut"/> + <c>ExitCode = 124</c>.
+    /// </summary>
+    /// <param name="command">The shell command to execute.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    Task<ShellResult> RunAsync(string command, CancellationToken cancellationToken = default);
+}