<!-- SPDX-License-Identifier: Apache-2.0 -->

# Tool configuration

`config/tools.toml` enables the built-in tools for an agent. It is required.

Each tool is enabled with a boolean. Unknown tool names are rejected during `dry-run` and startup, even when their value is `false`.

```toml
edit = true
read = true
respond = true
exec = false
```

## The exec tool

The `exec` tool runs commands through the agent sandbox and can be a boolean or a table. `exec = true` enables execution with the defaults below; `exec = false` disables it. The binary entrypoint list belongs in [`sandbox.toml`](sandbox.md#bubblewrap), not in this table.

```toml
[exec]
enabled = true
timeout = 60000
inline = true
inlineThresholdBytes = 16384
outputDir = "/workspace/.exec-output"
previewHead = 20
previewTail = 20
maxPreviewLineLength = 1000
hostEnvPassthrough = []
```

| Field                  | Default                   | Description                                                                                                                                        |
| ---------------------- | ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`              | `false`                   | Whether execution is enabled.                                                                                                                      |
| `timeout`              | `60000`                   | Command timeout in milliseconds.                                                                                                                   |
| `inline`               | `true`                    | Whether short output is returned inline.                                                                                                           |
| `inlineThresholdBytes` | `16384`                   | Inline output threshold in bytes.                                                                                                                  |
| `outputDir`            | `/workspace/.exec-output` | Output directory inside the sandbox.                                                                                                               |
| `previewHead`          | `20`                      | Preview lines from the start of file output.                                                                                                       |
| `previewTail`          | `20`                      | Preview lines from the end of file output.                                                                                                         |
| `maxPreviewLineLength` | `1000`                    | Maximum characters kept from any single preview line. Long lines are elided with a marker so minified or binary-ish output cannot flood the model. |
| `hostEnvPassthrough`   | `[]`                      | Host environment variables copied into the sandbox.                                                                                                |

The command timeout remains active while writing input and draining stdout/stderr, including after the command's parent process exits. A background child that inherits output handles cannot make output collection wait indefinitely. A timeout reports failure and retains stdout captured before the deadline; cancellation of the calling turn propagates as cancellation rather than a successful command result.

## Built-in tools

| Tool                   | Purpose                                              |
| ---------------------- | ---------------------------------------------------- |
| `respond`              | Send a message to the current or another channel.    |
| `no-response`          | End a turn without sending a message.                |
| `edit`                 | Targeted replacements in a file with fuzzy matching. |
| `read`                 | Read a file; large files return a section outline.   |
| `read-sections`        | Add sections of an opened file to context.           |
| `open-file`            | Pin a file or sections to session context.           |
| `close-file`           | Unpin a file from context.                           |
| `read-skill`           | Load a skill document.                               |
| `list-dir`             | List a sandbox directory.                            |
| `write`                | Create or overwrite a sandbox file.                  |
| `exec`                 | Run a command in the sandbox.                        |
| `read-history`         | Fetch message history from the current channel.      |
| `read-session`         | Read a persisted session's history.                  |
| `list-sessions`        | List persisted sessions.                             |
| `query-sessions`       | Search persisted session contents.                   |
| `download-attachments` | Download channel attachments into the sandbox.       |
| `react`                | Add an emoji reaction to a message.                  |
| `schedule`             | Schedule a one-shot task for a future time.          |
| `session-info`         | Describe the current session.                        |
| `prune-boundaries`     | Commit a topic compaction range.                     |

`edit` is the built-in targeted editing tool. CireilClaw 2.0.0 removes `str-replace` and migrates existing tool configuration to `edit`, preserving whether editing was enabled. Update custom tool calls and agent instructions to use `edit`; see the [editing tool migration](../operations/upgrades.md#v200-editing-tool-migration) for the configuration and argument changes.

`read` rejects text files larger than 262144 bytes (256 KiB) with an error before returning content or generating an outline. This limit also applies when `raw` is enabled. Use sandboxed commands through `exec`, when enabled and permitted, to extract a smaller excerpt into a separate file, then read that file. Image and video reads use their existing media handling rather than this text limit.

Plugin tools must also be enabled here by name; see [Plugins](plugins.md).

`read-session` limits each rendered thinking block to 200 characters and appends `… (truncated)` when more content remains.

## Reload

Changes to `tools.toml` are picked up by the running runtime and apply to subsequent turns. An in-progress turn keeps the tool set it started with.