feat(langchain_v1): Add ShellToolMiddleware and ClaudeBashToolMiddleware (#33527)

- Both middleware share the same implementation, the only difference is
one uses Claude's server-side tool definition, whereas the other one
uses a generic tool definition compatible with all models
- Implemented 3 execution policies (responsible for actually running the
shell process)
- HostExecutionPolicy runs the shell as subprocess, appropriate for
already sandboxed environments, eg when run inside a dedicated docker
container
- CodexSandboxExecutionPolicy runs the shell using the sandbox command
from the Codex CLI which implements sandboxing techniques for Linux and
Mac OS.
- DockerExecutionPolicy runs the shell inside a dedicated Docker
container for isolation.
- Implements all behaviours described in
https://docs.claude.com/en/docs/agents-and-tools/tool-use/bash-tool#handle-large-outputs
including timeouts, truncation, output redaction, etc

---------

Co-authored-by: Sydney Runkle <54324534+sydney-runkle@users.noreply.github.com>
Co-authored-by: Sydney Runkle <sydneymarierunkle@gmail.com>
Co-authored-by: Eugene Yurtsev <eyurtsev@gmail.com>

libs/partners/anthropic/langchain_anthropic/middleware/__init__.py

@@ -6,6 +6,7 @@ from langchain_anthropic.middleware.anthropic_tools import (
     StateClaudeMemoryMiddleware,
     StateClaudeTextEditorMiddleware,
 )
+from langchain_anthropic.middleware.bash import ClaudeBashToolMiddleware
 from langchain_anthropic.middleware.file_search import (
     StateFileSearchMiddleware,
 )
@@ -15,6 +16,7 @@ from langchain_anthropic.middleware.prompt_caching import (
 
 __all__ = [
     "AnthropicPromptCachingMiddleware",
+    "ClaudeBashToolMiddleware",
     "FilesystemClaudeMemoryMiddleware",
     "FilesystemClaudeTextEditorMiddleware",
     "StateClaudeMemoryMiddleware",

libs/partners/anthropic/langchain_anthropic/middleware/bash.py

@@ -0,0 +1,92 @@
+"""Anthropic-specific middleware for the Claude bash tool."""
+
+from __future__ import annotations
+
+from collections.abc import Awaitable, Callable
+from typing import Any, Literal
+
+from langchain.agents.middleware.shell_tool import ShellToolMiddleware
+from langchain.agents.middleware.types import ModelRequest, ModelResponse
+from langchain.tools.tool_node import ToolCallRequest
+from langchain_core.messages import ToolMessage
+from langgraph.types import Command
+
+_CLAUDE_BASH_DESCRIPTOR = {"type": "bash_20250124", "name": "bash"}
+
+
+class ClaudeBashToolMiddleware(ShellToolMiddleware):
+    """Middleware that exposes Anthropic's native bash tool to models."""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        """Initialize middleware without registering a client-side tool."""
+        kwargs["shell_command"] = ("/bin/bash",)
+        super().__init__(*args, **kwargs)
+        # Remove the base tool so Claude's native descriptor is the sole entry.
+        self._tool = None  # type: ignore[assignment]
+        self.tools = []
+
+    def wrap_model_call(
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelResponse:
+        """Ensure the Claude bash descriptor is available to the model."""
+        tools = request.tools
+        if all(tool is not _CLAUDE_BASH_DESCRIPTOR for tool in tools):
+            tools = [*tools, _CLAUDE_BASH_DESCRIPTOR]
+            request = request.override(tools=tools)
+        return handler(request)
+
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Command | ToolMessage],
+    ) -> Command | ToolMessage:
+        """Intercept Claude bash tool calls and execute them locally."""
+        tool_call = request.tool_call
+        if tool_call.get("name") != "bash":
+            return handler(request)
+        resources = self._ensure_resources(request.state)
+        return self._run_shell_tool(
+            resources,
+            tool_call["args"],
+            tool_call_id=tool_call.get("id"),
+        )
+
+    async def awrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], Awaitable[Command | ToolMessage]],
+    ) -> Command | ToolMessage:
+        """Async interception mirroring the synchronous implementation."""
+        tool_call = request.tool_call
+        if tool_call.get("name") != "bash":
+            return await handler(request)
+        resources = self._ensure_resources(request.state)
+        return self._run_shell_tool(
+            resources,
+            tool_call["args"],
+            tool_call_id=tool_call.get("id"),
+        )
+
+    def _format_tool_message(
+        self,
+        content: str,
+        tool_call_id: str | None,
+        *,
+        status: Literal["success", "error"],
+        artifact: dict[str, Any] | None = None,
+    ) -> ToolMessage | str:
+        """Format tool responses using Claude's bash descriptor."""
+        if tool_call_id is None:
+            return content
+        return ToolMessage(
+            content=content,
+            tool_call_id=tool_call_id,
+            name=_CLAUDE_BASH_DESCRIPTOR["name"],
+            status=status,
+            artifact=artifact or {},
+        )
+
+
+__all__ = ["ClaudeBashToolMiddleware"]

libs/partners/anthropic/tests/unit_tests/middleware/test_bash.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock
+
+import pytest
+from langchain_core.messages.tool import ToolCall
+
+pytest.importorskip(
+    "anthropic", reason="Anthropic SDK is required for Claude middleware tests"
+)
+
+from langchain.tools.tool_node import ToolCallRequest
+from langchain_core.messages import ToolMessage
+
+from langchain_anthropic.middleware.bash import ClaudeBashToolMiddleware
+
+
+def test_wrap_tool_call_handles_claude_bash(monkeypatch: pytest.MonkeyPatch) -> None:
+    middleware = ClaudeBashToolMiddleware()
+    sentinel = ToolMessage(content="ok", tool_call_id="call-1", name="bash")
+
+    monkeypatch.setattr(middleware, "_run_shell_tool", MagicMock(return_value=sentinel))
+    monkeypatch.setattr(
+        middleware, "_ensure_resources", MagicMock(return_value=MagicMock())
+    )
+
+    tool_call: ToolCall = {
+        "name": "bash",
+        "args": {"command": "echo hi"},
+        "id": "call-1",
+    }
+    request = ToolCallRequest(
+        tool_call=tool_call,
+        tool=MagicMock(),
+        state={},
+        runtime=None,  # type: ignore[arg-type]
+    )
+
+    handler_called = False
+
+    def handler(_: ToolCallRequest) -> ToolMessage:
+        nonlocal handler_called
+        handler_called = True
+        return ToolMessage(content="should not be used", tool_call_id="call-1")
+
+    result = middleware.wrap_tool_call(request, handler)
+    assert result is sentinel
+    assert handler_called is False
+
+
+def test_wrap_tool_call_passes_through_other_tools(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    middleware = ClaudeBashToolMiddleware()
+    tool_call: ToolCall = {"name": "other", "args": {}, "id": "call-2"}
+    request = ToolCallRequest(
+        tool_call=tool_call,
+        tool=MagicMock(),
+        state={},
+        runtime=None,  # type: ignore[arg-type]
+    )
+
+    sentinel = ToolMessage(content="handled", tool_call_id="call-2", name="other")
+
+    def handler(_: ToolCallRequest) -> ToolMessage:
+        return sentinel
+
+    result = middleware.wrap_tool_call(request, handler)
+    assert result is sentinel