# `Alloy.Tool.Core.Bash`
[🔗](https://github.com/alloy-ex/alloy/blob/v0.10.1/lib/alloy/tool/core/bash.ex#L1)

Built-in tool: execute shell commands via `bash -rc` (restricted shell).

Returns stdout/stderr merged with the exit code appended. Output is
truncated at 30,000 characters to prevent context overflow.
Commands that exceed the timeout are killed and return an error.

## Security

By default, commands run in restricted bash (`bash -r`), which prevents:
- Changing directories with `cd`
- Setting or unsetting `SHELL`, `ENV`, `BASH_ENV`, or `PATH`
- Specifying commands containing `/`
- Redirecting output with `>`, `>>`, etc.

Set `:bash_restricted` to `false` in the agent's `:context` map to
disable restricted mode.

Configure `:allowed_paths` in context to restrict file tool access.

## Usage

    config = %{tools: [Alloy.Tool.Core.Bash], ...}

The agent can then call:

    %{command: "ls -la", timeout: 5000}

# `executor`

```elixir
@type executor() :: (command :: String.t(), dir :: String.t() ->
                 {String.t(), non_neg_integer()})
```

A custom command executor. Receives the shell command string and the working
directory path, and must return `{output, exit_code}`.

The default executor calls `System.cmd/3`. Supply a custom executor via
the `:bash_executor` key in the agent's `:context` map to sandbox or
proxy shell execution.

---

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