> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentuse.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Built-in Tools

> Configuration reference for built-in filesystem, bash, and artifact tools

AgentUse provides built-in tools for file operations, command execution, and session-linked artifacts. This reference documents their configuration options and path matching behavior.

## Path Matching Behavior

Filesystem paths and Bash `allowedPaths` use **containment-based** path matching by default:

| Pattern           | Mode        | Matches                                  |
| ----------------- | ----------- | ---------------------------------------- |
| `${root}`         | Containment | All files under project root             |
| `${root}/src`     | Containment | All files under src directory            |
| `${root}/**/*.ts` | Glob        | Only `.ts` files anywhere in project     |
| `${root}/*.json`  | Glob        | Only `.json` files in root (not subdirs) |

**Rule:** If the path contains glob characters (`*`, `?`, `[`), it uses glob matching. Otherwise, it uses containment (path = path/\*\*).

## Filesystem Tool

Controls access for Read, Write, and Edit operations. Granting a permission exposes the matching tool to the agent: `read` → `filesystem_read`, `write` → `filesystem_write` (and `filesystem_edit`), `edit` → `filesystem_edit`.

### Configuration

```yaml theme={"system"}
tools:
  filesystem:
    - path: ${root}
      permissions: [read]
    - path: ${root}/src
      permissions: [read, write]   # write also grants edit
    - paths:
        - ${root}/docs
        - ${root}/tests
      permissions: [read]
```

### Fields

| Field         | Type           | Description                                          |
| ------------- | -------------- | ---------------------------------------------------- |
| `path`        | `string`       | Single path or pattern                               |
| `paths`       | `string[]`     | Multiple paths or patterns (alternative to `path`)   |
| `permissions` | `Permission[]` | Array of allowed operations: `read`, `write`, `edit` |

### Permission Model

The capability hierarchy is `read` \< `edit` \< `write`:

* **`read`** — read file contents.
* **`edit`** — replace strings inside an *existing* file (cannot create new files or overwrite a file wholesale).
* **`write`** — create or overwrite any file. Because this is strictly stronger than `edit`, **granting `write` also grants `edit`** (the agent gets both the write and edit tools).

In practice this means `[read, write]` is all most agents need — the agent can read, do targeted edits, and do full writes. List `edit` on its own only when you want the narrower grant: modify existing files but never create or clobber them.

<Note>
  Prefer `[read, write]` over `[read, write, edit]` — `edit` is redundant alongside `write`. Use `[read, edit]` deliberately when an agent should tweak existing files without the ability to create or overwrite them.
</Note>

### Path Variables

| Variable      | Description                                     |
| ------------- | ----------------------------------------------- |
| `${root}`     | Project root directory                          |
| `${agentDir}` | Directory containing the agent file             |
| `${tmpDir}`   | System temp directory (or custom if configured) |
| `~`           | User's home directory                           |

### Examples

```yaml theme={"system"}
# Containment mode (recommended for most cases)
filesystem:
  - path: ${root}
    permissions: [read, write]   # read + edit + write

# Restrict to specific subdirectory
filesystem:
  - path: ${root}/src
    permissions: [read, write]
  - path: ${root}/docs
    permissions: [read]

# Fine-grained control with glob patterns
filesystem:
  - path: ${root}/**/*.ts
    permissions: [edit]          # edit existing files only, no create/overwrite
  - path: ${root}/**/*.md
    permissions: [read]
```

### Read Limits

`read_file` returns up to **2000 lines** per call by default (`AGENTUSE_TOOL_MAX_LINES`); pass an explicit `limit` to read more, or an `offset` to page through a larger file. Individual lines longer than **2000 characters** (`AGENTUSE_TOOL_MAX_LINE_LENGTH`) are truncated with a `... (truncated)` suffix. See [Tool Output environment variables](/reference/environment-variables#tool-output) to tune these.

### Edit Operations

The edit tool replaces exact strings rather than rewriting whole files. It uses fuzzy matching to tolerate minor whitespace, indentation, and line-ending differences. **Prefer editing over full writes on large files** — rewriting a large file regenerates its entire contents as output tokens, which is slow and can exhaust a run's time budget.

A single edit replaces one string:

| Parameter     | Type      | Description                                                  |
| ------------- | --------- | ------------------------------------------------------------ |
| `file_path`   | `string`  | Absolute path to the file                                    |
| `old_string`  | `string`  | Exact string to find and replace                             |
| `new_string`  | `string`  | Replacement string                                           |
| `replace_all` | `boolean` | Replace all occurrences (default: `false`, first match only) |

To make several changes in one call, pass an `edits` array instead of the top-level `old_string`/`new_string`:

| Parameter   | Type     | Description                                         |
| ----------- | -------- | --------------------------------------------------- |
| `file_path` | `string` | Absolute path to the file                           |
| `edits`     | `Edit[]` | Array of `{ old_string, new_string, replace_all? }` |

Batched edits apply **sequentially** (each to the result of the previous) and are **all-or-nothing**: if any edit fails to match, the file is left unchanged. Provide either the single form or the `edits` array, not both.

## Artifact Tools

Artifact tools let an agent save substantial deliverables for the user to view in the session UI without granting broad filesystem write access.

### Configuration

```yaml theme={"system"}
tools:
  artifacts: true
```

Optional custom project-relative directory:

```yaml theme={"system"}
tools:
  artifacts:
    dir: .agentuse/artifacts
```

When enabled, the agent receives:

| Tool            | Description                                                                                                                   |
| --------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `artifact_save` | Save a report, plan, spec, HTML page, chart, or other deliverable under the artifact directory and link it to the current run |
| `artifact_list` | List saved artifacts from the manifest, filterable by current session or group                                                |

`artifact_save` writes under `.agentuse/artifacts/` by default, records metadata in a manifest, and returns a viewable session URL when a session is active. Markdown artifacts can include `title` and `tags`, which are merged into frontmatter. To read an artifact's content later, use `filesystem_read` on the returned path.

## Bash Tool

Controls which shell commands can be executed and in which directories.

### Configuration

```yaml theme={"system"}
tools:
  bash:
    commands:
      - "git *"
      - "npm *"
      - "pnpm *"
    allowedPaths:
      - /tmp
      - ~/workspace
    timeout: 120000
```

### Fields

| Field          | Type       | Default  | Description                                           |
| -------------- | ---------- | -------- | ----------------------------------------------------- |
| `commands`     | `string[]` | Required | Allowlist of command patterns (supports `*` wildcard) |
| `allowedPaths` | `string[]` | `[]`     | Additional directories beyond project root            |
| `timeout`      | `number`   | `120000` | Command timeout in milliseconds                       |

### Command Patterns

Commands use simple wildcard matching:

| Pattern       | Matches                                        |
| ------------- | ---------------------------------------------- |
| `git *`       | Any git command (git status, git commit, etc.) |
| `npm install` | Only `npm install` (exact match)               |
| `*`           | Any command (use with caution)                 |

### allowedPaths Behavior

The `allowedPaths` field uses **containment** - a path grants access to all files and subdirectories within it:

```yaml theme={"system"}
bash:
  allowedPaths:
    - /tmp           # Allows /tmp, /tmp/foo, /tmp/foo/bar, etc.
    - ~/workspace    # Allows all of ~/workspace/**
```

<Note>
  Project root is always accessible for bash commands. Use `allowedPaths` for directories outside the project.
</Note>

### Examples

```yaml theme={"system"}
# Development setup with common tools
bash:
  commands:
    - "git *"
    - "npm *"
    - "pnpm *"
    - "bun *"
    - "tsc *"
    - "eslint *"

# CI/CD with restricted access
bash:
  commands:
    - "npm test"
    - "npm run build"
  timeout: 300000

# Multi-project setup
bash:
  commands:
    - "git *"
    - "make *"
  allowedPaths:
    - ~/projects/shared-lib
    - /opt/tools
```

### Output Limits

Command output is capped at **30KB** (`AGENTUSE_TOOL_MAX_OUTPUT_BYTES`) before it reaches the model. When output exceeds the cap, AgentUse keeps a **head + tail** slice (40% head / 60% tail by default) and drops the middle, inserting a marker such as `... [N chars truncated of M total] ...`. The head preserves errors and context that often appear early; the tail preserves the most recent output. The result's metadata flags `truncated: true`.

Because every tool result is re-sent to the model on each subsequent step, a single large output inflates input-token usage for the rest of the run. Prefer commands that emit only what you need, for example `git diff --stat` instead of a full `git diff` over high-churn files. See [Tool Output environment variables](/reference/environment-variables#tool-output) to tune the caps.

## Sandbox Tool

When a `sandbox` is configured in the agent frontmatter, the `sandbox__exec` tool is injected for running commands inside the Docker container. File I/O is handled by the filesystem tool — no separate sandbox file tools are needed.

<Note>
  The sandbox tool is only available when `sandbox` is configured. See the [Sandbox guide](/guides/sandbox) for setup instructions.
</Note>

### `sandbox__exec`

Execute a shell command inside the Docker container.

| Parameter | Type     | Default      | Description                            |
| --------- | -------- | ------------ | -------------------------------------- |
| `command` | `string` | Required     | Shell command to execute               |
| `cwd`     | `string` | Project root | Working directory inside the container |

Returns `stdout`, `stderr`, and `exitCode`.

### Mount Mode

Each filesystem path is mounted at its **real host path** with per-path mode derived from permissions:

* **Read-only** — No `write` or `edit` permissions for that path
* **Read-write** — `write` or `edit` permissions granted for that path

Paths inside the container mirror the host (no `/workspace/` alias). Changes made by the filesystem tool on the host are visible inside the container via the bind mount.

## Security Considerations

### Filesystem Tool

* **Sensitive files blocked**: `.env`, `.env.local`, etc. are blocked by default
* **Symlink resolution**: Symlinks are resolved to prevent escape attacks
* **Path traversal prevention**: `../` sequences are normalized and validated

### Bash Tool

* **Command allowlist**: Only explicitly allowed commands can run
* **Directory restrictions**: Commands can only access project root and `allowedPaths`
* **Environment sanitization**: Dangerous environment variables are cleared
* **Timeout enforcement**: Commands are killed after timeout

<Warning>
  Be careful with broad command patterns like `*` or `bash *`. Prefer explicit command allowlists.
</Warning>