# `Codex.Tools.ShellTool`
[🔗](https://github.com/nshkrdotcom/codex_sdk/blob/v0.18.1/lib/codex/tools/shell_tool.ex#L1)

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)

---

*Consult [api-reference.md](api-reference.md) for complete listing*