Filesystem & code tools

These are the tools your agent reaches for most: running commands, reading and changing files, searching the codebase, extracting text from PDFs, and driving git. They all operate against the workspace directory and are enforced by Revka’s security policy — path allowlists, the autonomy level, and the per-hour action budget all apply before any file or process is touched.

All nine tools on this page are part of the default tool registry, so they’re available even in a minimal configuration. For the full tool catalog, see the Tools overview.

Note

Paths are resolved relative to the workspace root. A path that resolves outside the workspace (including via .. or symlinks) is rejected unless it falls under an explicit allowlist entry. See Policy, commands & sandboxing.

shell

Execute an arbitrary shell command in the workspace directory.

{ "command": "cargo test --workspace", "approved": false }

Field	Type	Default	Meaning
command	string	— (required)	The shell command to execute.
approved	boolean	false	Set true to explicitly approve medium/high-risk commands in supervised mode.

Behavior and limits:

• Output cap: command output is truncated at 1 MB.
• Timeout: the command is killed after 60 s by default. Override with shell_tool.timeout_secs.
• Sanitized environment: the process environment is cleared and only a safe allowlist is re-added (PATH, HOME, TERM, LANG, USER, SHELL, TMPDIR on Unix; PATH, PATHEXT, USERPROFILE, SYSTEMROOT, COMSPEC, TEMP, and similar on Windows). API keys and other secrets are never passed through. If a script depends on a custom variable, add its name to security.shell_env_passthrough or set it inline in the command itself.
• Sandbox: commands run through a sandbox layer. The default NoopSandbox runs the command directly; a real sandbox (when configured) wraps execution with additional isolation.
• Approval gating: in supervised mode, the security policy classifies command risk. Medium/high-risk commands are blocked unless approved: true is passed. Read-only policy and the rate limiter can also block execution.

Caution

shell is the most powerful tool on this page. Lock it down with the command allowlist/denylist and OTP gating described in Policy, commands & sandboxing and OTP gating & emergency stop.

file_read

Read a file’s contents with line numbers. Supports partial reads via offset/limit, extracts plain text from PDFs inline, and reads other binary files with lossy UTF-8 conversion.

{ "path": "src/main.rs", "offset": 1, "limit": 50 }

Field	Type	Default	Meaning
path	string	— (required)	File path. Relative paths resolve from the workspace; outside paths require a policy allowlist entry.
offset	integer	1	Starting line number (1-based).
limit	integer	all lines	Maximum number of lines to return.

• Size cap: files larger than 10 MB are rejected.
• PDF text: file_read extracts text from a PDF inline — you do not need a separate pdf_read call to read a PDF’s text. Use pdf_read when you want to control extraction limits explicitly.

file_write

Write content to a file in the workspace, creating any missing parent directories.

{ "path": "output/report.md", "content": "# Report\n\n..." }

Field	Type	Default	Meaning
path	string	— (required)	Destination path within the workspace.
content	string	— (required)	Full file content to write.

This is a full overwrite, not an append — any existing file at path is replaced in its entirety. For surgical changes to an existing file, prefer file_edit.

file_edit

Replace an exact string in a file with new content. Safer than rewriting the whole file for targeted changes.

{
  "path": "src/main.rs",
  "old_string": "fn hello() {\n    println!(\"hi\");\n}",
  "new_string": "fn hello_world() {\n    println!(\"hello, world\");\n}"
}

Field	Type	Default	Meaning
path	string	— (required)	File to edit.
old_string	string	— (required)	Exact text to find and replace.
new_string	string	— (required)	Replacement text.

old_string must match exactly once. If it matches zero times, or more than once, the edit is rejected with an error (old_string matches N times; must match exactly once). Include enough surrounding context — typically a few lines — so the match is unique.

Tip

When an edit fails because the string matches multiple times, widen old_string with adjacent lines rather than narrowing it. To replace several distinct occurrences, issue one file_edit call per location.

glob_search

Find files matching a glob pattern within the workspace. Returns a sorted list of matching paths, relative to the workspace root.

{ "pattern": "src/**/*.rs" }

Field	Type	Default	Meaning
pattern	string	— (required)	Glob pattern, e.g. **/*.rs, src/**/mod.rs, docs/*.md.

Use glob_search to locate files by name or path shape. To search inside file contents, use content_search instead.

content_search

Search file contents by regular expression within the workspace. Uses ripgrep (rg) when available and falls back to grep -rn -E otherwise. Regex syntax is ripgrep-compatible (Rust regex).

{ "pattern": "fn main", "include": "*.rs", "output_mode": "content", "context_after": 2 }

Field	Type	Default	Meaning
pattern	string	— (required)	Regular expression to search for.
path	string	.	Directory to search.
output_mode	string	content	content (matching lines), files_with_matches (paths only), or count (match counts per file).
include	string	—	File glob filter, e.g. *.rs.
case_sensitive	boolean	true	Set false for case-insensitive matching.
context_before	integer	0	Lines of context to show before each match.
context_after	integer	0	Lines of context to show after each match.
multiline	boolean	false	Enable multiline matching. Requires ripgrep — errors on the grep fallback.
max_results	integer	1000	Maximum number of results to return.

Output modes:

• content — the matching lines themselves (combine with context_before/context_after for surrounding lines).
• files_with_matches — only the paths of files containing a match. Best for “which files mention X”.
• count — the number of matches per file.

semantic_code_search

Find relevant code snippets using a token-efficient search adapter. It tries Semble first (when installed), then ripgrep, then a built-in literal scanner — an automatic fallback chain.

{ "query": "context compression for tool outputs", "top_k": 5 }

Field	Type	Default	Meaning
query	string	— (required)	Natural-language or symbol query.
path	string	.	Directory to search.
top_k	integer	8	Maximum results to return (clamped to 25 max).
backend	string	auto	auto, semble, or literal.

Backends:

• auto — prefers Semble when the semble binary is on PATH; otherwise falls back to ripgrep, then the built-in literal scanner.
• semble — forces the Semble sidecar. If Semble isn’t installed, the tool returns an actionable error (Install with pip install semble or uv tool install semble, or use backend='literal').
• literal — skips Semble and uses ripgrep or the built-in scanner directly.

Semble is an optional Python MCP sidecar. See Install the Python MCP sidecars to set it up.

pdf_read

Extract plain text from a PDF file in the workspace.

{ "path": "docs/spec.pdf", "max_chars": 50000 }

Field	Type	Default	Meaning
path	string	— (required)	Path to the PDF file.
max_chars	integer	50000	Maximum characters to return (hard ceiling 200000). Output beyond the limit is truncated with a marker.

• Size cap: PDFs larger than 50 MB are rejected.
• Image-only / encrypted PDFs: these return a successful result whose output is the warning PDF contains no extractable text (may be image-only or encrypted) rather than an error — there is simply no text layer to extract.
• Build feature: PDF extraction requires the rag-pdf Cargo feature. In a build without it, pdf_read is still registered but returns a clear error: PDF extraction is not enabled. Rebuild with: cargo build --features rag-pdf. See Cargo feature flags & ADRs.

Note

file_read also extracts PDF text inline. Use pdf_read when you specifically want to cap output with max_chars or read a PDF up to the larger 50 MB limit.

git_operations

Perform structured git operations against the workspace’s git working tree, with parsed JSON output and autonomy-level enforcement.

{ "operation": "status" }

{ "operation": "commit", "message": "fix: resolve race condition" }

Field	Type	Meaning
operation	string (required)	One of status, diff, log, branch, commit, add, checkout, stash.
message	string	Commit message (for commit).
paths	string	File paths to stage (for add).
branch	string	Branch name (for checkout).
files	string	File or path to diff (for diff, default .).
cached	boolean	Show staged changes (for diff).
limit	integer	Number of log entries to return (for log, default 10).
stash_action	string	push, pop, list, or drop (for stash).
path	string	Optional subdirectory within the workspace to run the operation in. Defaults to the workspace root.

Autonomy enforcement: write operations (commit, add, checkout, stash) require a higher autonomy level. In read-only policy mode they are blocked (git write operations require higher autonomy level), while status, diff, log, and branch always work. See Autonomy levels & approvals.

Argument safety: git arguments are sanitized to prevent injection. Options that could execute arbitrary code or bypass hooks — --exec=, --upload-pack=, --receive-pack=, --pager=, --editor=, --no-verify, -c, command substitution (`, $(...)), and shell metacharacters (|, ;, >) — are rejected.

Tip

For operations the structured tool doesn’t expose (for example push, merge, or rebase), use the shell tool with a git command, subject to the same command policy and approval gating.

Related pages

• Tools overview — the full tool catalog and how registration works.
• Security model and Policy, commands & sandboxing — path allowlists, command gating, and sandboxing.
• Autonomy levels & approvals — how read-only / supervised / full modes affect write tools.
• Configuration: channels, tools & integrations — config keys such as shell_tool.timeout_secs and security.shell_env_passthrough.
• Code agents, delegation & pipelines — delegating larger coding tasks to Claude Code, Codex, and others.