Tools

Each agent has access to a set of tools that the LLM can invoke during its agentic loop. Tools are defined as OpenAI-compatible function calling schemas and executed server-side on the agent VM.

The list below documents the tools exposed by the current first-wave agent backend. Some clients may reserve names for upcoming compatibility tools, but if a tool is not listed here it is not available from this backend yet.

Tool reference

bash

Execute a shell command and return stdout, stderr, and exit code.

Parameter	Type	Required	Description
command	string	yes	The bash command to execute
timeout	integer	no	Timeout in seconds (default 60, max 300)

Output is limited to 30,000 characters in chat. When a workspace is configured, oversized output is saved under workspace/tool-results/ and the tool returns a preview plus the saved path. Without a workspace, output falls back to in-band truncation. Commands that exceed the timeout are killed and return a timeout message.

Safety guards: Before execution, every command is checked against a set of deny patterns. Blocked commands return an error without being executed. See Security model below.

read_file

Read a file and return its contents with line numbers.

Parameter	Type	Required	Description
path	string	yes	Absolute or workspace-relative path
offset	integer	no	Line number to start from (1-based)
limit	integer	no	Maximum number of lines to read

Output format is <line_number>\t<content> per line, matching common editor conventions. Output is truncated at 30,000 characters.

Images (png, jpg, gif, webp, bmp) are returned visually to the model. PDFs should be read with read_pdf. Other binary files return metadata and inspection hints instead of raw binary content.

read_pdf

Read a PDF as extracted text or rendered page images.

Parameter	Type	Required	Description
path	string	yes	Absolute or workspace-relative path
pages	string	no	Page selector such as "1", "1-3", or "2,5,8" (default "1")
mode	string	no	"text" (default) or "image"

Text mode reads up to 20 selected pages. Image mode renders up to 3 selected pages for visual analysis of layout, diagrams, or tables.

read_many_files

Read up to 20 text files in one call.

Parameter	Type	Required	Description
paths	array	yes	File paths to read
offset	integer	no	Line number to start from for every file
limit	integer	no	Maximum lines per file

This uses the same workspace boundary and read-hash tracking as read_file, so files read here can be safely edited later in the same turn.

write_file

Write content to a file, creating parent directories as needed.

Parameter	Type	Required	Description
path	string	yes	Absolute or workspace-relative path
content	string	yes	The content to write

edit_file

Find and replace an exact string in a text file.

Parameter	Type	Required	Description
path	string	yes	Absolute or workspace-relative path
old_string	string	yes	The exact string to find
new_string	string	yes	The replacement string
replace_all	boolean	no	If true, replace every occurrence. Defaults to false
expected_hash	string	no	Optional SHA-256 hash the file must match before editing

Returns an error if old_string is not found in the file. By default the old string must appear exactly once; if it appears multiple times, pass replace_all: true to replace all occurrences. Binary files are rejected. If expected_hash is provided, the edit is refused unless the current file content matches that hash. Without expected_hash, the agent must have read the file earlier in the same turn and the file must still match the recorded read hash.

multi_edit

Apply multiple edit_file operations in order.

Parameter	Type	Required	Description
edits	array	yes	Ordered edits with path, old_string, new_string, optional replace_all, and optional expected_hash

Execution stops after the first failed edit. Each edit follows the same read-before-edit and stale-file guards as edit_file.

apply_patch

Apply a unified diff patch to files in the workspace.

Parameter	Type	Required	Description
patch	string	yes	Unified diff text accepted by git apply

The patch is validated with git apply --check before it is applied. The tool is hidden when git is not installed.

glob

Find files by filename pattern inside the workspace.

Parameter	Type	Required	Description
pattern	string	yes	Glob pattern such as "*.py" or "**/*.md"
path	string	no	Directory to search within (defaults to workspace root)
limit	integer	no	Maximum results to return (default 100, max 500)

Results are sorted by modification time, newest first. Paths that escape the workspace are rejected. Dotfiles and dot-directories (.git, .env, etc.) are not matched by * or **/*; match them explicitly with patterns like .* or **/.git/**.

grep

Search text files with ripgrep inside the workspace.

Parameter	Type	Required	Description
pattern	string	yes	Search pattern passed to ripgrep
path	string	no	File or directory to search (defaults to workspace root)
output_mode	string	no	content, files_with_matches, or count
type_filter	string	no	Optional ripgrep type filter, such as py, ts, or md
case_sensitive	boolean	no	If false, run case-insensitive search
limit	integer	no	Maximum output lines to return (default 200, max 1000)

The tool is hidden from the model when rg is not installed.

git_status

Return git status --short --branch for the workspace repository.

git_diff

Return a git diff for workspace changes.

Parameter	Type	Required	Description
path	string	no	Optional path to limit the diff
staged	boolean	no	If true, show staged diff

git_show

Show a git object or commit.

Parameter	Type	Required	Description
rev	string	no	Revision or object to show, default HEAD
path	string	no	Optional path to limit output

git_blame

Show git blame for a file.

Parameter	Type	Required	Description
path	string	yes	File to blame
start	integer	no	Optional starting line
end	integer	no	Optional ending line

run_tests, run_lint, run_typecheck, run_format

Run verification or formatting commands in the workspace and return stdout, stderr, and exit code.

Parameter	Type	Required	Description
command	string	yes	Command to run
timeout	integer	no	Timeout in seconds (default 120, max 600)

These tools share the same command safety checks as bash. run_format is classified as mutating; the other verification wrappers are read-only but are also treated as shell tools for ask-before-shell policy mode.

list_dir

List contents of a directory with type prefixes.

Parameter	Type	Required	Description
path	string	no	Directory path (defaults to workspace root)

Output format uses [dir] and [file] prefixes, sorted with directories first.

web_fetch

Fetch a URL and return its text content.

Parameter	Type	Required	Description
url	string	yes	URL to fetch (http or https)

HTML content is automatically stripped of tags and decoded. JSON responses are pretty-printed. Output is truncated at 50,000 characters. Requests follow up to 5 redirects and time out after 30 seconds.

search_history

Search past conversation history using full-text search. Useful for recalling what was discussed about a topic, finding details from previous conversations, or checking if something was mentioned before.

Parameter	Type	Required	Description
query	string	yes	Search query. Supports FTS5 syntax: words, "exact phrases", OR, NOT, prefix*
chat_id	string	no	Limit search to a specific conversation
limit	integer	no	Maximum results to return (default 20, max 50)

Results include the matched message snippet, timestamp, role, and chat ID. Output is truncated at 30,000 characters.

Set summarize to true to ask the model to synthesize an answer from the matched history instead of returning raw snippets.

remember_fact

Store a compact typed memory record.

Parameter	Type	Required	Description
kind	string	yes	Category such as user_fact, repo_convention, test_command, or decision
content	string	yes	Declarative memory text, max 2,000 characters
source	string	no	Source label, default agent
metadata	object	no	Optional structured metadata

Use this for stable facts that should remain useful later. Do not use it for temporary task progress or stale-by-next-week information.

search_memory

Search typed memory records.

Parameter	Type	Required	Description
query	string	no	Text to search for; empty lists recent records
kind	string	no	Optional memory category filter
limit	integer	no	Maximum records to return (default 20, max 100)
include_archived	boolean	no	Whether archived records should be returned

web_search

Search the web using LibertAI Search. Returns titles, URLs, and snippets.

Parameter	Type	Required	Description
query	string	yes	The search query
count	integer	no	Number of results, 1-10 (default 5)

Requires a valid LIBERTAI_API_KEY. The search aggregates results from multiple engines (Google, Bing, DuckDuckGo). Failed engines are noted in the output.

generate_image

Generate an image from a text prompt using LibertAI’s image generation API.

Parameter	Type	Required	Description
prompt	string	yes	Text description of the image
size	string	no	Dimensions as "WxH" (default "1024x1024", max 1024 per side, multiples of 16)
steps	integer	no	Generation steps (default 8 for speed, use 14 for higher quality or text readability)

The generated image is saved to workspace/images/<uuid>.png and automatically sent to the user.

todo

Manage a structured task list stored in the workspace.

Parameter	Type	Required	Description
action	string	yes	One of add, list, update, complete, delete
title	string	for add	Task title
id	integer	for update, complete, delete	Task ID
status	string	no	New status for update
priority	string	no	low, medium, or high
notes	string	no	Additional task notes

execute_code

Execute a Python script that can call agent tools programmatically without adding each intermediate tool result to the conversation context.

Parameter	Type	Required	Description
code	string	yes	Python code to execute
timeout	integer	no	Timeout in seconds (default 120, max 300)

The script receives a call_tool(name, **kwargs) helper for invoking tools such as bash, read_file, write_file, edit_file, list_dir, web_fetch, and web_search. Printed stdout is returned and truncated at 30,000 characters.

checkpoint

Create, list, restore, or diff lightweight git checkpoints for the workspace.

Parameter	Type	Required	Description
action	string	yes	One of create, list, restore, diff
message	string	for create	Checkpoint message
id	string	for restore, diff	Checkpoint ID/SHA

process

Manage long-running background processes.

Parameter	Type	Required	Description
action	string	yes	One of start, list, poll, kill
command	string	for start	Shell command to start
id	string	for poll, kill	Process ID

Process output is buffered and cleared after each poll. The buffer keeps the latest 10 KB of combined stdout/stderr.

send_file

Send a file from the workspace to the user.

Parameter	Type	Required	Description
path	string	yes	Path to the file (relative to workspace or absolute within workspace)
caption	string	no	Optional caption

Files are validated against the workspace boundary and sensitive file list. Maximum file size is 50 MB.

spawn

Spawn a background subagent to work on a task asynchronously. Not available to subagents (prevents recursive spawning).

Parameter	Type	Required	Description
task	string	yes	Task description for the subagent
label	string	no	Short label for the task (defaults to first 50 chars of task)
role	string	no	Typed role: default, explorer, worker, reviewer, verifier, or researcher
persona	string	no	System prompt override for the subagent
timeout	integer	no	Wall-clock timeout in seconds (default 300, max 600)

Subagents run with a restricted tool set (no further spawning) and a maximum of 45 tool iterations. Results are delivered as pending messages. Up to 5 subagents can run concurrently per chat. The typed role adds built-in guidance for common delegation patterns; persona remains available for extra task-specific instructions.

Security model

Workspace boundary

All file operations (read_file, read_many_files, write_file, edit_file, multi_edit, apply_patch, list_dir, send_file) enforce a strict workspace boundary. Paths are resolved against the workspace root and checked after symlink resolution. Any path that escapes the workspace directory is rejected with a PathSecurityError.

Tool execution also separates read-only and mutating tools. Read-only calls from the same model response may run in parallel; mutating tools such as bash, apply_patch, write_file, edit_file, multi_edit, todo, checkpoint, process, run_format, and execute_code are serialized in model-specified order.

Relative paths are treated as relative to the workspace. Absolute paths must still fall within the workspace boundary.

Sensitive file protection

Certain filenames are blocked from being read or served, even within the workspace:

• .env — Contains secrets and API keys
• agent.db, agent.db-shm, agent.db-wal — Internal SQLite database files

Bash deny patterns

The bash tool checks every command against a set of regex deny patterns before execution. Matching commands are blocked immediately. The patterns prevent:

Destructive system commands:

• rm -rf / or rm -rf ~ — Recursive deletion of root or home
• mkfs, format, diskpart — Disk formatting
• dd if= — Raw disk writes
• > /dev/sd* — Writing to block devices
• shutdown, reboot, poweroff, halt — System shutdown
• Fork bombs (:(){ ... };:)
• systemctl stop baal-agent — Stopping the agent service
• kill -9 1 — Killing PID 1

Secret exfiltration:

• env, printenv, set — Environment variable dumps
• export -p, declare -x — Export listing
• /proc/*/environ — Process environment files
• Any .env file access
• /run/secrets — Container secrets

File size limits

• Tool output: 30,000 characters in chat; oversized output is saved to tool-results/ when possible
• Web content: 50,000 characters
• File uploads/sends: 50 MB

Availability

Some tools are advertised only when their runtime dependencies are available. For example, web_search and generate_image require LIBERTAI_API_KEY, grep requires rg, and the git tools require git. The /info endpoint reports hidden tools and reasons in unavailable_tools.

Oversized tool output returns a saved path in-band, not a separate artifact event yet. Clients should render the preview text normally and may link the path through existing file download APIs.