Repository navigation
Tool Permissions
The model works by calling tools: searching the web, reading a file, running a command. This page explains every built-in tool, whether it is on when you install, and when it stops to ask you first.
Every tool call has to pass two separate checks, and they never blend into one score:
-
May this tool be called at all? That is
tool_permissionsinconfig.yaml. A tool switched off there is never offered to the model, and nothing else can switch it back on: not an agent, a skill, a project'ssettings.jsonor an environment variable. -
Does this call need you to approve it? That is
tool_approvalsinconfig.yaml, plus a per-call check for the tools whose risk depends on their arguments (the file tools and the shell).
The rule that ties them together is stricter always wins. An agent or a skill can narrow the tools the model may use and add approval prompts, but it can never remove one. That matters because agents and skills can arrive inside a repository you cloned.
In the TUI, /config sets either table and asks you to confirm first, naming what the key permits:
/config tool_permissions.read true
/config tool_approvals.web_search true
Or edit the two tables in config.yaml by hand. Installation says where that file is. Either way the change applies at the next launch: the harness reads these settings once, at startup, so nothing running in a session can change them. /config offers to relaunch for you.
Turning an approval on adds a prompt and is always safe. Turning one off removes a prompt you would otherwise see, so think about what the tool can do first; the sections below say.
When a call needs approval, the harness shows you the tool and its arguments and waits for your yes or no. When nothing can ask you (a piped CLI run, or an unattended research pass), the tools that need approval are not offered to the model at all, rather than offered and refused. Being unable to ask is never treated as permission to proceed.
On means switched on in a fresh install. Asks is the shipped approval behaviour.
| Tool | What it does | On | Asks |
|---|---|---|---|
web_search |
Searches the web | yes | no |
fetch_url |
Reads a web page or PDF by URL | yes | no |
arxiv_search |
Searches arXiv for papers | yes | no |
get_time |
Tells the model the current date and time (UTC) | yes | no |
symbolic_math, linear_algebra, probability_stats, discrete_math, logic, geometry
|
Exact maths | yes | no |
read |
Reads a file | no | outside the workspace |
view_image |
Looks at an image file | no | outside the workspace |
write |
Creates or overwrites a file | no | outside the workspace |
edit |
Replaces one exact span of text in a file | no | outside the workspace |
shell |
Runs a command | no | by approval mode |
shell_background, shell_monitor
|
Start a command that keeps running | no | by approval mode |
shell_interactive |
Opens a shell the model can type into | no | by approval mode |
shell_input |
Types a line into that open shell | no | no (see below) |
shell_sessions, shell_output, shell_kill
|
List, read and stop this conversation's sessions | no | no |
ask_user |
Asks you a question | yes | no |
todo_write |
Keeps a visible checklist | yes | no |
pin, unpin
|
Protects recent turns from being summarised, or releases them | yes | no |
load_skill |
Reads a skill's full instructions | yes | no |
read_project_doc |
Reads one of the project's docs | yes | no |
write_project_doc |
Writes one of the project's standard docs | yes | always |
remember |
Saves a fact for future conversations | yes | always |
spawn_subagent |
Hands a task to another agent | yes | always |
MCP tools (mcp__<server>__<tool>) |
Whatever the server provides | yes | always, unless the server is set to auto-approve |
On, and never ask. They only read public information, and the harness checks every request.
-
web_searchsearches the web for current information. -
fetch_urlreturns a page's readable text, without the site's menus, banners and scripts. Links are marked[L1],[L2]with their URLs listed beside the text, and a PDF's text comes back page by page. A long document is read 5,000 characters at a time. Every URL is checked before the request and again at every redirect: addresses on your own network, loopback, and the cloud metadata address are refused, and so is any domain on the blocked list. Downloads are capped at 2 MB for a page and 32 MB for a PDF (fetch_max_html_mbandfetch_max_pdf_mb). -
arxiv_searchsearches arXiv by keyword and category, and returns titles, authors, abstracts, dates and PDF links. -
get_timereturns the current date and time in UTC.
Pages you fetch stay subject to their sites' terms. The harness does not bypass paywalls or ignore rate limits.
symbolic_math, linear_algebra, probability_stats, discrete_math, logic and geometry. On, and never ask. They are pure calculations on their arguments: algebra and calculus, matrices, statistics and distributions, number theory and combinatorics, propositional logic, and classical geometry. Results are exact unless the model asks for a number.
Each call runs in a separate process that is stopped after 20 seconds (tool_compute_timeout_s), with CPU and memory ceilings on Linux, so a call on a huge number cannot hang the turn. When one is stopped, the model is told which tool and which limit, so it can ask for something smaller.
read, view_image, write and edit are off in a fresh install, and only you can turn them on, in config.yaml.
Once on, each call is decided by its path:
-
Inside the workspace: runs without asking. The workspace is the
workspacefolder in the directory you launched from, unless you setAGENT_WORKSPACE(which also makes it the project) orworkspace_dirinconfig.yaml. -
Outside the workspace: asks every time, including the rest of your project when the workspace is its
workspacesubfolder. -
Any path through a
.venastinefolder: refused outright, wherever it is, even through a symlink or a hard link. That folder holds the agents, skills and MCP server definitions that feed your future sessions, so a tool must not rewrite it.
To have the model work on your whole project without a prompt per file, launch with AGENT_WORKSPACE set to the project folder. Before you do, remember what that means: the model can then change any file there without asking.
What each one does:
-
readreturns a file's text, at most 500 lines or 50,000 characters per call, and pages through longer files. PDF, DOCX, PPTX, XLSX and HTML files are converted to Markdown first when the optionaldocumentsextra is installed. A file over 25 MB is refused before it is opened. -
view_imageattaches a PNG, JPEG, GIF or WEBP image (up to 3,932,160 bytes) so the model sees the picture itself. It is only offered when the provider is markedaccepts_imagesinproviders.json, and never inside a research pass. -
writecreates or overwrites a file, creating parent folders as needed. In the TUI, every finishedwriteoreditshows its diff in the transcript. -
editreplaces one span of text that must appear exactly once in the file; zero or several matches is an error rather than a guess.
shell and the seven session tools are off in a fresh install. When you turn shell on, shell_approval_mode decides which commands ask: the shipped tiered mode runs only read-only commands inside the workspace without asking, and asks about everything else. Commands run inside a Docker or Podman container where one is available. Shell and Sandbox covers the modes, where commands run, and the WSL and SSH backends.
-
shellruns one command and returns its output. -
shell_backgroundstarts a command that keeps running (a test suite, a build, a server) and wakes the model when it finishes.shell_monitordoes the same and also wakes it each time a line of output matches a pattern. -
shell_interactiveopens a shell in the container and keeps it open, for a REPL or a database client. -
shell_inputtypes a line into that open shell. It does not ask, because approving the shell approved what is typed into it. A line naming a protected path still asks. Settool_approvals.shell_inputtotrueto be asked about every line. -
shell_sessions,shell_outputandshell_killlist, read and stop this conversation's own sessions, so they never ask.
On, and never ask. They act only on the current conversation.
-
ask_userasks you a question and waits for your answer. It is deliberately never gated: a tool that needs approval is hidden wherever nothing can ask, so gating the tool whose whole job is asking would make it invisible. -
todo_writekeeps a checklist you can see, for multi-step work. -
pinkeeps the most recent turns word for word when a long conversation is summarised.unpinreleases them. Both are limited to this thread and can be undone. -
load_skillreads the full instructions of a skill listed in the model's prompt. It is offered only when there is a skill to load.
-
read_project_docreads one of the project's documentation or manifest files: Markdown, text and manifest files only, inside the project folder, at most 20,000 characters per call. It never asks. On a fresh install it is how agents read your project, sincereadis off. -
write_project_docalways asks. It writes one of the standard documents/initcreates (AGENTS.md,ARCHITECTURE.mdand so on). It takes a document's name, not a path, so it cannot write anywhere else, but it overwrites that file, andAGENTS.mdfeeds the instructions of later sessions.
-
rememberalways asks. It saves a fact that outlives the conversation, for this project or for everything, and memories shape conversations you have not started yet. That is why it is never available to an unattended research run. List them with/memories(or--memories) and delete one with/forget(or--forget <id>).
-
spawn_subagentalways asks. It hands a self-contained task to one of the spawnable agents, which runs in its own thread and returns its answer.
When you approve a spawn, you are asked which of the child's approval-gated tools it may use without asking again, one tick box per tool, all unticked by default. Running it with none selected is fine. A child can never have more tools than its parent. Spawns nest at most two deep, and at most three from one response run at once.
Tools from an MCP server are named mcp__<server>__<tool> and ask on every call, unless you set "autoApprove": true on that server in mcp.json. They are third-party code the model can reach. See MCP Servers.
A ten-pass research run has no one at the keyboard for minutes at a time, so tools that need approval are hidden from it unless you do one of these:
venastine --mode research --grant "query" # pick tools from a list
venastine --mode research --grant-tools mcp__files__search "query"
venastine --mode research --attended "query" # be asked about each call as it happens-
Only a tool with no per-call check can be pre-granted. In practice that means MCP tools, so on an install with no MCP server the list is empty. The file tools and
shelldecide from each call's arguments, so ticking "shell" would approve commands you never saw; those still ask, or stay hidden. -
spawn_subagentandremembercan never be pre-granted. Approving a spawn signs off the child's whole tool set, and a memory outlives the run. -
write_project_doccan be signed off for one subagent turn, but never pre-granted to an unattended run. - A grant lasts one run and is never saved, and a project's settings cannot add one.
- With
--attended, an approval left unanswered for 600 seconds denies that one call, and the run continues.
The README covers the reasoning behind each rule.
Whatever a tool's permissions, two checks apply to every call in every mode:
- Arguments are refused, not rewritten. A call whose arguments contain something shaped like a credential, or a URL on the blocked list, is refused.
-
Results are redacted. Anything key-shaped in a tool's output becomes
[REDACTED]before it reaches the model, the transcript, the database or the log.
Checked against release 0.3.12 (commit f33ef8a). The README's What needs approval by default table is the reference, and a test keeps it in step with the code.
Start here
Guides
Reference