Merge branch 'main' into peibekwe/declarative-bugfix-python-new

python/samples/02-agents/harness/README.md

@@ -17,6 +17,7 @@ from a chat client.
 | AgentModeProvider | Plan/execute mode tracking |
 | MemoryContextProvider | File-based durable memory (when `memory_store` provided) |
 | SkillsProvider | File-based skill discovery and progressive loading |
+| Shell tool | Shell command execution + environment probing (when `shell_executor` provided) |
 | OpenTelemetry | Built-in observability |
 
 Each feature can be disabled or customized via keyword arguments.
@@ -91,3 +92,25 @@ agent = create_harness_agent(
 The `AgentModeProvider` enables a two-phase workflow:
 1. **Plan mode** — Interactive: the agent asks questions, creates todos, gets approval
 2. **Execute mode** — Autonomous: the agent works through todos independently
+
+### Shell Tool
+
+Pass a shell executor (e.g. `LocalShellTool` from `agent-framework-tools`) to enable shell
+command execution plus automatic environment probing via a `ShellEnvironmentProvider`. The
+tool is only wired when the chat client supports shell tools; otherwise a warning is logged
+and the shell tool/provider are skipped. The caller owns the executor's lifecycle.
+
+```python
+from agent_framework_tools.shell import LocalShellTool, ShellEnvironmentProviderOptions
+
+async with LocalShellTool(acknowledge_unsafe=True) as shell:
+    agent = create_harness_agent(
+        client=client,
+        max_context_window_tokens=128_000,
+        max_output_tokens=16_384,
+        shell_executor=shell,
+        # Optional: customize environment probing.
+        shell_environment_provider_options=ShellEnvironmentProviderOptions(probe_tools=("git", "python")),
+    )
+```
+