Path Matching Behavior
Filesystem paths and BashallowedPaths use containment-based path matching by default:
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
Fields
Permission Model
The capability hierarchy isread < 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 thanedit, grantingwritealso grantsedit(the agent gets both the write and edit tools).
[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.Reading images and PDFs
filesystem_read returns text files with line numbers, but it also reads images (PNG, JPEG, GIF, WebP) and PDFs, handing the actual image or document to the model so an agent can reason over a chart, screenshot, or scanned page directly. File type is detected by content (magic bytes), not by extension.
This requires a model whose input modalities include image/pdf (Claude, GPT-4o, Gemini, and most modern models). On a text-only model, an image/PDF read returns a clear error instead of breaking the run. The same path allowlist applies as for text reads. Size caps: images up to ~5MB, PDFs up to ~32MB; offset/limit are ignored for media files.
Path Variables
Examples
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:
To make several changes in one call, pass an
edits array instead of the top-level old_string/new_string:
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
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.
Metrics Tool
The metrics tool lets an agent record business-metric facts (counts and amounts) about work it just completed, e.g. “chased 4 invoices totaling $11,200”. Records land in the reserved sharedmetrics store and roll up on the serve Home page and over the JSON API, so the numbers a dashboard shows are deterministic tool writes, never model-computed sums.
Configuration
Fields
At least one of
value or count is required.
Idempotency
Records are upserted keyed on(sessionId, metric): a retried or resumed run overwrites its own earlier record instead of double-counting, and recording the same metric twice in one run is last-write-wins. This is what makes the numbers trustworthy enough to display. Runs without a session id (rare) cannot be deduplicated and always create a new record.
The runtime stamps sessionId and the agent id onto every record; the model cannot spoof provenance. Each record is a regular store item (type: "metric", tagged with the metric name) in .agentuse/store/metrics/, browsable at /stores/metrics and readable programmatically via GET /api/stores/metrics. In mock mode tool execution is simulated, so no metric records are persisted.
Bash Tool
Controls which shell commands can be executed and in which directories.Configuration
Fields
When no config timeout is set, the model may pass a per-call
timeout: a duration string, or a bare number meaning milliseconds (kept for model familiarity). A bare per-call number under 1000 is rejected with a corrective error (it is always a seconds-vs-milliseconds mixup; a real sub-second timeout must be written as "500ms").
Command Patterns
Commands use simple wildcard matching:allowedPaths Behavior
TheallowedPaths field uses containment - a path grants access to all files and subdirectories within it:
Project root is always accessible for bash commands. Use
allowedPaths for directories outside the project.Examples
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.
Sandbox Tool
When asandbox 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.
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
writeoreditpermissions for that path - Read-write,
writeoreditpermissions granted for that path
/workspace/ alias). Changes made by the filesystem tool on the host are visible inside the container via the bind mount.
Run Outcome Tool
Thereport_incomplete tool is always available, no configuration needed. It lets an agent declare that the run finished cleanly but did not achieve its objective, a blocked precondition, an expired login, a dead dependency.
report_incomplete
Calling it does not stop the run: the agent continues (store writes, final report) and the tool call is just recorded. When the run ends, the session is persisted as
error with code INCOMPLETE instead of completed:
- Session list (CLI and web) shows an
incompletestatus instead of a greencompleted - Channel notifications fire the
failureevent, notcompletion agentuse sessions showdisplays the reason under the error section
✅ Complete: <one-line outcome> or ⚠️ Incomplete: <reason>. Agent files should not restate this mechanic; only add domain judgment about what counts as blocked vs. legitimately empty.
Use it for “ran fine but delivered nothing because something is broken” (e.g. a scraper whose login session died). Do not use it for a legitimately empty result, a sweep that found nothing to act on is still
completed.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