feat(anthropic): support bash tool

Author: christian-bromann

libs/providers/langchain-anthropic/README.md

@@ -506,6 +506,67 @@ const response2 = await llm.invoke(
 
 For more information, see [Anthropic's Code Execution Tool documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/code-execution-tool).
 
+### Bash Tool
+
+The bash tool (`bash_20250124`) enables shell command execution in a persistent bash session. Unlike the sandboxed code execution tool, this tool requires you to provide your own execution environment.
+
+> **⚠️ Security Warning:** The bash tool provides direct system access. Implement safety measures such as running in isolated environments (Docker/VM), command filtering, and resource limits.
+
+The bash tool provides:
+
+- **Persistent bash session** - Maintains state between commands
+- **Shell command execution** - Run any shell command
+- **Environment access** - Access to environment variables and working directory
+- **Command chaining** - Support for pipes, redirects, and scripting
+
+Available commands:
+
+- Execute a command: `{ command: "ls -la" }`
+- Restart the session: `{ restart: true }`
+
+```typescript
+import {
+  ChatAnthropic,
+  tools,
+  type Bash20250124Command,
+} from "@langchain/anthropic";
+import { execSync } from "child_process";
+
+const llm = new ChatAnthropic({
+  model: "claude-sonnet-4-5-20250929",
+});
+
+const bash = tools.bash_20250124({
+  execute: async (args: Bash20250124Command) => {
+    if (args.restart) {
+      // Reset session state
+      return "Bash session restarted";
+    }
+    try {
+      const output = execSync(args.command!, {
+        encoding: "utf-8",
+        timeout: 30000,
+      });
+      return output;
+    } catch (error) {
+      return `Error: ${(error as Error).message}`;
+    }
+  },
+});
+
+const llmWithBash = llm.bindTools([bash]);
+
+const response = await llmWithBash.invoke(
+  "List all Python files in the current directory"
+);
+
+// Process tool calls and execute commands
+console.log(response.tool_calls?.[0].name); // "bash"
+console.log(response.tool_calls?.[0].args.command); // "ls -la *.py"
+```
+
+For more information, see [Anthropic's Bash Tool documentation](https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/bash-tool).
+
 ## Development
 
 To develop the Anthropic package, you'll need to follow these instructions:

libs/providers/langchain-anthropic/src/tools/bash.ts

@@ -0,0 +1,124 @@
+import { tool } from "@langchain/core/tools";
+import type { DynamicStructuredTool, ToolRuntime } from "@langchain/core/tools";
+
+import type { Bash20250124Command } from "./types.js";
+
+/**
+ * Options for the bash tool.
+ */
+export interface Bash20250124Options {
+  /**
+   * Optional execute function that handles bash command execution.
+   * This function receives the command input and should return the result
+   * (stdout and stderr combined, or an error message).
+   */
+  execute?: (args: Bash20250124Command) => string | Promise<string>;
+}
+
+/**
+ * Creates an Anthropic bash tool for Claude 4 models and Claude 3.7 that enables
+ * shell command execution in a persistent bash session.
+ *
+ * The bash tool provides Claude with:
+ * - **Persistent bash session**: Maintains state between commands
+ * - **Shell command execution**: Run any shell command
+ * - **Environment access**: Access to environment variables and working directory
+ * - **Command chaining**: Support for pipes, redirects, and scripting
+ *
+ * Available commands:
+ * - Execute a command: `{ command: "ls -la" }`
+ * - Restart the session: `{ restart: true }`
+ *
+ * @warning The bash tool provides direct system access. Implement safety measures
+ * such as running in isolated environments (Docker/VM), command filtering,
+ * and resource limits.
+ *
+ * @example
+ * ```typescript
+ * import { ChatAnthropic, tools } from "@langchain/anthropic";
+ * import { execSync } from "child_process";
+ *
+ * const llm = new ChatAnthropic({
+ *   model: "claude-sonnet-4-5-20250929",
+ * });
+ *
+ * const bash = tools.bash_20250124({
+ *   execute: async (args) => {
+ *     if (args.restart) {
+ *       // Reset session state
+ *       return "Bash session restarted";
+ *     }
+ *     try {
+ *       const output = execSync(args.command!, {
+ *         encoding: "utf-8",
+ *         timeout: 30000,
+ *       });
+ *       return output;
+ *     } catch (error) {
+ *       return `Error: ${error.message}`;
+ *     }
+ *   },
+ * });
+ *
+ * const llmWithBash = llm.bindTools([bash]);
+ * const response = await llmWithBash.invoke(
+ *   "List all Python files in the current directory"
+ * );
+ *
+ * // Outputs: "bash"
+ * console.log(response.tool_calls[0].name);
+ * // Outputs: "ls -la *.py 2>/dev/null || echo \"No Python files found in the current directory\"
+ * console.log(response.tool_calls[0].args.command);
+ * ```
+ *
+ * @example Multi-step automation
+ * ```typescript
+ * // Claude can chain commands in a persistent session:
+ * // 1. cd /tmp
+ * // 2. echo "Hello" > test.txt
+ * // 3. cat test.txt  // Works because we're still in /tmp
+ * ```
+ *
+ * @param options - Configuration options for the bash tool
+ * @param options.execute - Function that handles bash command execution
+ * @returns The bash tool object that can be passed to `bindTools`
+ *
+ * @see https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/bash-tool
+ */
+export function bash_20250124(
+  options?: Bash20250124Options
+): DynamicStructuredTool {
+  const name = "bash";
+  const bashTool = tool(
+    options?.execute as (
+      input: unknown,
+      runtime: ToolRuntime<unknown, unknown>
+    ) => string | Promise<string>,
+    {
+      name,
+      schema: {
+        type: "object",
+        properties: {
+          command: {
+            type: "string",
+            description: "The bash command to run",
+          },
+          restart: {
+            type: "boolean",
+            description: "Set to true to restart the bash session",
+          },
+        },
+      },
+    }
+  );
+
+  bashTool.extras = {
+    ...(bashTool.extras ?? {}),
+    providerToolDefinition: {
+      type: "bash_20250124",
+      name,
+    },
+  };
+
+  return bashTool;
+}

libs/providers/langchain-anthropic/src/tools/index.ts

@@ -8,6 +8,7 @@ import {
 import { textEditor_20250728 } from "./textEditor.js";
 import { computer_20251124, computer_20250124 } from "./computer.js";
 import { codeExecution_20250825 } from "./codeExecution.js";
+import { bash_20250124 } from "./bash.js";
 
 export const tools = {
   memory_20250818,
@@ -19,6 +20,7 @@ export const tools = {
   computer_20251124,
   computer_20250124,
   codeExecution_20250825,
+  bash_20250124,
 };
 
 export type * from "./types.js";

libs/providers/langchain-anthropic/src/tools/tests/bash.int.test.ts

@@ -0,0 +1,57 @@
+import { expect, it, describe } from "vitest";
+import { AIMessage, HumanMessage } from "@langchain/core/messages";
+import { execSync } from "child_process";
+
+import { ChatAnthropic } from "../../chat_models.js";
+import { bash_20250124 } from "../bash.js";
+
+const createModel = () =>
+  new ChatAnthropic({
+    model: "claude-sonnet-4-5",
+    temperature: 0,
+  });
+
+describe("Anthropic Bash Tool Integration Tests", () => {
+  it("bash tool can be bound to ChatAnthropic and triggers tool use", async () => {
+    const llm = createModel();
+
+    const bash = bash_20250124({
+      execute: async (args) => {
+        if (args.restart) {
+          return "Bash session restarted";
+        }
+        try {
+          const output = execSync(args.command!, {
+            encoding: "utf-8",
+            timeout: 10000,
+          });
+          return output;
+        } catch (error) {
+          return `Error: ${(error as Error).message}`;
+        }
+      },
+    });
+
+    const llmWithBash = llm.bindTools([bash]);
+
+    const response = await llmWithBash.invoke([
+      new HumanMessage("What is 2+2? Use bash to calculate it with echo."),
+    ]);
+
+    expect(AIMessage.isInstance(response)).toBe(true);
+    expect(response.tool_calls?.[0]).toEqual(
+      expect.objectContaining({
+        name: "bash",
+        type: "tool_call",
+        args: expect.objectContaining({
+          command: "echo $((2+2))",
+        }),
+      })
+    );
+
+    const result = await bash.invoke({
+      command: response.tool_calls?.[0]?.args?.command,
+    });
+    expect(result).toBe("4\n");
+  }, 60000);
+});

libs/providers/langchain-anthropic/src/tools/tests/bash.test.ts

@@ -0,0 +1,95 @@
+import { expect, it, describe } from "vitest";
+import { bash_20250124 } from "../bash.js";
+
+describe("Anthropic Bash Tool Unit Tests", () => {
+  describe("bash_20250124", () => {
+    it("creates a valid bash tool with no options", () => {
+      const bash = bash_20250124();
+
+      expect(bash.name).toBe("bash");
+      expect(bash.extras?.providerToolDefinition).toMatchInlineSnapshot(`
+        {
+          "name": "bash",
+          "type": "bash_20250124",
+        }
+      `);
+    });
+
+    it("creates a valid bash tool with execute function", async () => {
+      const mockExecute = async (args: {
+        command?: string;
+        restart?: boolean;
+      }) => {
+        if (args.restart) {
+          return "Session restarted";
+        }
+        return `Executed: ${args.command}`;
+      };
+
+      const bash = bash_20250124({
+        execute: mockExecute,
+      });
+
+      expect(bash.name).toBe("bash");
+      expect(bash.func).toBeDefined();
+    });
+
+    it("has correct schema for bash commands", () => {
+      const bash = bash_20250124();
+
+      expect(bash.schema).toMatchInlineSnapshot(`
+        {
+          "properties": {
+            "command": {
+              "description": "The bash command to run",
+              "type": "string",
+            },
+            "restart": {
+              "description": "Set to true to restart the bash session",
+              "type": "boolean",
+            },
+          },
+          "type": "object",
+        }
+      `);
+    });
+
+    it("can execute a command", async () => {
+      let executedCommand: string | undefined;
+
+      const bash = bash_20250124({
+        execute: async (args) => {
+          if (args.command) {
+            executedCommand = args.command;
+            return "command output";
+          }
+          return "no command";
+        },
+      });
+
+      const result = await bash.invoke({ command: "ls -la" });
+
+      expect(result).toBe("command output");
+      expect(executedCommand).toBe("ls -la");
+    });
+
+    it("can restart the session", async () => {
+      let wasRestarted = false;
+
+      const bash = bash_20250124({
+        execute: async (args) => {
+          if (args.restart) {
+            wasRestarted = true;
+            return "Bash session restarted";
+          }
+          return "command executed";
+        },
+      });
+
+      const result = await bash.invoke({ restart: true });
+
+      expect(result).toBe("Bash session restarted");
+      expect(wasRestarted).toBe(true);
+    });
+  });
+});

libs/providers/langchain-anthropic/src/tools/types.ts

@@ -196,3 +196,29 @@ export interface ComputerZoomAction {
   /** Coordinates [x1, y1, x2, y2] defining top-left and bottom-right corners */
   region: [number, number, number, number];
 }
+
+/**
+ * Bash tool command types for Claude 4 models and Claude 3.7.
+ * @see https://docs.anthropic.com/en/docs/agents-and-tools/tool-use/bash-tool
+ */
+export type Bash20250124Command =
+  | Bash20250124ExecuteCommand
+  | Bash20250124RestartCommand;
+
+/**
+ * Execute a bash command.
+ */
+export interface Bash20250124ExecuteCommand {
+  /** The bash command to run */
+  command: string;
+  restart?: never;
+}
+
+/**
+ * Restart the bash session to reset state.
+ */
+export interface Bash20250124RestartCommand {
+  command?: never;
+  /** Set to true to restart the bash session */
+  restart: true;
+}