Tools

Every tool the agent can call is defined in the built-in registry (src/tools/runner.ts). All inputs and outputs are validated with Zod schemas before and after execution. Tools have a risk class (read_only / write / execute) that the permission system uses to decide whether approval is needed.

Built-in tool catalogue

Filesystem

Tool	Risk	Description
fs.list	read	List files/directories; supports recursive walk, hidden files, up to 5 000 entries
fs.read	read	Read a file as UTF-8 with byte-level offset/limit slicing (max 512 KB per call)
fs.write	write	Write a full file payload; auto-creates parent directories
fs.edit	write	Apply Unified Diff patches to one or more files in one call
fs.cd	execute	Change the agent’s working directory for the current run

Search

Tool	Risk	Description
search.rg	read	Full-text regex search via ripgrep (JSON output, grouped by file with snippets and context lines); falls back to Node walker when rg is not available
search.files	read	List project files respecting .gitignore and standard ignore dirs (node_modules, dist, .git, __pycache__, etc.); uses rg --files or Node walker
search.fuzzy	read	Fuzzy-score file paths; returns ranked results with match indices

Shell

Tool	Risk	Description
shell.exec	execute	Run a command through the host shell (bash -lc on Unix, powershell.exe -Command on Windows); timeout up to 120 s; stdout/stderr captured; timedOut flag

Git (exposed only when gitEnabled: true is set on the run)

Tool	Risk	Description
git.status	execute	git status --porcelain=v1 --branch — branch, upstream, ahead/behind, per-file index/worktree status
git.diff	execute	git diff patch + numstat; supports --cached and configurable context lines
git.apply	write	Apply a patch via git apply; supports --check (dry-run) and --cached
git.commit	write	git commit -m <message>; optionally -a to stage all tracked changes
git.push	execute	Push branch to remote; uses --force-with-lease instead of --force
git.pull	execute	Pull from remote; optional --rebase

Web

Tool	Risk	Description
web.search	execute	Search the web and return ranked URLs with snippets; requires web mode cached or live; provider-agnostic (DuckDuckGo, Jina, SearXNG, Brave, Tavily)
web.fetch	read	Fetch a URL as clean markdown via Jina Reader (primary) or raw HTML fallback; maxChars up to 100 000

Permission presets

Three presets gate what tools the agent may call without asking:

Preset	Writes	Execute/Shell/Git
chat-readonly	No	No
agent-default	Gated by approval	Gated by approval
exec-full	Yes	Yes

The permission manager evaluates each non-read-only call against the preset and any stored permission rules. The result is one of allow, ask (show an approval dialog in the TUI), or deny.

External tools

rg and git are resolved at runtime from: custom path in settings.json → PATH → bundled fallback. Status for each external tool is visible in umbra doctor.

Custom tools

Add custom tool paths in ~/.umbra/settings.json under tools.customPaths:

{
  "tools": {
    "customPaths": {
      "rg": "/usr/local/bin/rg",
      "git": "/opt/homebrew/bin/git"
    }
  }
}