Codex.Tools.ShellTool (Codex SDK v0.7.2)

Copy Markdown View Source

Hosted tool for executing shell commands.

Overview

ShellTool provides a fully-featured shell command execution environment with approval integration, timeout handling, and output truncation. It can be used standalone or registered in the tool registry.

Options

Options can be passed during registration or via context metadata:

  • :executor - Custom executor function (default: built-in shell executor)
  • :approval - Approval callback or policy for command review
  • :max_output_bytes - Maximum output size before truncation (default: 10,000)
  • :timeout_ms - Command timeout in milliseconds (default: 60,000)
  • :cwd - Default working directory
  • :env - Environment variables map

Usage

Direct Invocation

args = %{"command" => ["bash", "-lc", "ls -la"], "workdir" => "/tmp"}
{:ok, result} = Codex.Tools.ShellTool.invoke(args, %{})
# => %{"output" => "...", "exit_code" => 0, "success" => true}

With Registry

{:ok, _handle} = Codex.Tools.register(Codex.Tools.ShellTool,
  max_output_bytes: 5000,
  timeout_ms: 30_000,
  approval: fn cmd, _ctx -> :ok end
)

{:ok, result} =
  Codex.Tools.invoke("shell", %{"command" => ["bash", "-lc", "echo hello"]}, %{})

Approval Integration

The approval callback can be:

  • A 2-arity function fn(command, context) -> :ok | {:deny, reason}

  • A 3-arity function fn(command, context, metadata) -> :ok | {:deny, reason}

  • A module implementing review_tool/2 callback

Custom Executor

The executor callback receives (args, context, metadata) and should return:

  • {:ok, output} - where output is a string or map
  • {:error, reason} - on failure

For testing, provide a mock executor:

executor = fn %{"command" => cmd}, _ctx, _meta ->
  {:ok, %{"output" => "mocked: #{cmd}", "exit_code" => 0}}
end

{:ok, _} = Codex.Tools.register(Codex.Tools.ShellTool, executor: executor)