# `Planck.Agent.BuiltinTools`
[🔗](https://github.com/alexdesousa/planck/blob/v0.1.0/lib/planck/agent/builtin_tools.ex#L1)

Factory functions for the four built-in tools: `read`, `write`, `edit`, `bash`.

These tools cover file system access and shell execution. Together they are
sufficient for most agent tasks — reading context, writing code, applying
edits, and running scripts (including skill scripts).

Shell execution uses `erlexec` (`:exec`) which manages process groups and
cleans up child processes on timeout or termination.

## Usage

    tools = [
      Planck.Agent.BuiltinTools.read(),
      Planck.Agent.BuiltinTools.write(),
      Planck.Agent.BuiltinTools.edit(),
      Planck.Agent.BuiltinTools.bash()
    ]

Pass these alongside any inter-agent tools when starting an agent.

# `bash`

```elixir
@spec bash() :: Planck.Agent.Tool.t()
```

Returns the `bash` tool — runs a shell command via `erlexec`.

Process groups are cleaned up on timeout or termination. Both stdout and
stderr are captured; stderr is appended to the output when non-empty.

`cwd` and `timeout` are optional tool arguments supplied by the caller at
runtime — they are not baked into the tool at construction time.

# `edit`

```elixir
@spec edit() :: Planck.Agent.Tool.t()
```

Returns the `edit` tool — replaces an exact string in a file.

Fails if `old_string` is not found or appears more than once. Make
`old_string` long enough to be unique in the file.

# `read`

```elixir
@spec read() :: Planck.Agent.Tool.t()
```

Returns the `read` tool — reads the contents of a file from disk.

Supports optional `offset` (lines to skip from the start) and `limit`
(maximum number of lines to return) for reading large files in chunks.
Uses line-by-line streaming so only the requested portion is loaded.

# `write`

```elixir
@spec write() :: Planck.Agent.Tool.t()
```

Returns the `write` tool — writes content to a file.

Creates the file and any missing parent directories. Overwrites if the file
already exists.

---

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