<!-- 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; enabling an unknown tool is rejected.

```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.

```toml
[exec]
enabled = true
timeout = 60000
inline = true
inlineThresholdBytes = 16384
outputDir = "/workspace/.exec-output"
previewHead = 20
previewTail = 20
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. |
| `hostEnvPassthrough` | `[]` | Host environment variables copied into the sandbox. |

## 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. |
| `str-replace` | Replace one literal occurrence in a file. |
| `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` supersedes `str-replace`; when `edit` is enabled, `str-replace` is marked deprecated in the tool descriptions shown to the model.

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.