::docs :: reference

tools

Every built-in tool, its risk tier, and what it actually does — files, shell, web, calculator, clock, knowledge base, memory, and ask_user.

Every capability surfaces as a step in the plan you can watch, faces the same approval gate, runs locally where it can, and lands in a trace you can replay. /tools prints the live registry with each tool's tier; a tool's tier can be overridden with /policy risk <tool> <tier> [--save].

tooltierdoes
read_fileread_onlyread a workspace file
write_fileside_effectingwrite a workspace file (pre-write snapshot backs /undo; the gate shows a diff)
edit_fileside_effectinganchored string replace inside a file
list_directoryread_onlylist a workspace directory
search_filesread_onlycontent regex search across files
find_filesread_onlyfind files by name glob
run_shelldestructiverun a shell command in the workspace — always gated
web_searchread_only · untrustedkeyless DuckDuckGo search — no key, no account
web_extractread_only · untrustedfetch a page and extract its text locally (trafilatura); only the page's own host is contacted
calculateread_onlywhitelisted-AST arithmetic; refuses a bare value
current_timeread_onlythe machine's own clock
search_knowledge_baseread_only · untrustedretrieve from your ingested documents (RAG)
rememberside_effectingstore a durable fact
recallread_onlyread durable facts back
ask_userread_onlypause with one question; your answer resumes the turn
mcp_<server>_<tool>your declarationany tool from a configured MCP server

::files

File tools are sandboxed to the workspace (database/workspace/ by default). Every write takes a pre-write snapshot so /undo can revert a turn's file changes. The approval gate renders a write as a colored unified diff, says no change for a byte-identical rewrite, names an existing binary file as binary, and flags a path the sandbox will refuse as REFUSED.

::shell

run_shell hands the command to the host shell — PowerShell on Windows, /bin/sh on macOS/Linux — so write commands in your platform's native syntax. It is registered destructive, so it always hits the gate: the human seeing and approving the exact command is the safety boundary, not a path jail. Every run is a bounded foreground run with a timeout (shell.timeout, default 60 s); the child's environment is scrubbed of secret-shaped variables (shell.env_scrub); a command killed by a signal counts as a failed run. Prefix grants (/policy allow) let a reviewed command run unprompted next time, with the argument tail screened at every use.

::web

The web tools are API-less by design — a product whose pitch is "your data stays yours" shouldn't steer your search queries through a keyed SaaS backend. For deeper research the agent plans multiple search + read steps, visible in the rail and traced, rather than hiding them in a monolithic research tool. Both tools' output is untrusted and passes through the injection quarantine. web.max_results sets results per search.

::math and time

calculate evaluates arithmetic through a whitelisted AST — and refuses an expression that is a bare value, so a made-up number cannot be laundered into a "computed" result. current_time reads the machine clock, so "today" is computed, never guessed from memory.

::what is not a tool

http_request was removed. The MCP client is the integration surface: it does the same job with per-server trust declarations, outgoing-argument secret redaction, and connection status the generic tool never had — and with it gone, the list of ways anything can leave your machine is shorter to verify.