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) |
*, ?, [), it uses glob matching. Otherwise, it uses containment (path = path/**).
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
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.
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.
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
# 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 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) |
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? } |
edits array, not both.
Artifact tools let an agent save substantial deliverables for the user to view in the session UI without granting broad filesystem write access.
Configuration
Optional custom project-relative directory:
tools:
artifacts:
dir: .agentuse/artifacts
| 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.
Controls which shell commands can be executed and in which directories.
Configuration
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:
bash:
allowedPaths:
- /tmp # Allows /tmp, /tmp/foo, /tmp/foo/bar, etc.
- ~/workspace # Allows all of ~/workspace/**
Project root is always accessible for bash commands. Use allowedPaths for directories outside the project.
Examples
# 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 to tune the caps.
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.
The sandbox tool is only available when sandbox is configured. See the Sandbox guide for setup instructions. 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 |
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
- 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
- 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
Be careful with broad command patterns like * or bash *. Prefer explicit command allowlists.
