Skip to content

Tool Permissions

SolenopsisCampo edited this page Nov 8, 2026 · 1 revision

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.

Two questions, asked in order

Every tool call has to pass two separate checks, and they never blend into one score:

  1. May this tool be called at all? That is tool_permissions in config.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's settings.json or an environment variable.
  2. Does this call need you to approve it? That is tool_approvals in config.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.

Changing a permission

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.

What "asks you" means

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.

Every tool at a glance

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

Web and research tools

On, and never ask. They only read public information, and the harness checks every request.

  • web_search searches the web for current information.
  • fetch_url returns 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_mb and fetch_max_pdf_mb).
  • arxiv_search searches arXiv by keyword and category, and returns titles, authors, abstracts, dates and PDF links.
  • get_time returns 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.

Maths tools

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.

File tools

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 workspace folder in the directory you launched from, unless you set AGENT_WORKSPACE (which also makes it the project) or workspace_dir in config.yaml.
  • Outside the workspace: asks every time, including the rest of your project when the workspace is its workspace subfolder.
  • Any path through a .venastine folder: 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:

  • read returns 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 optional documents extra is installed. A file over 25 MB is refused before it is opened.
  • view_image attaches 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 marked accepts_images in providers.json, and never inside a research pass.
  • write creates or overwrites a file, creating parent folders as needed. In the TUI, every finished write or edit shows its diff in the transcript.
  • edit replaces one span of text that must appear exactly once in the file; zero or several matches is an error rather than a guess.

The shell and its sessions

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.

  • shell runs one command and returns its output.
  • shell_background starts a command that keeps running (a test suite, a build, a server) and wakes the model when it finishes. shell_monitor does the same and also wakes it each time a line of output matches a pattern.
  • shell_interactive opens a shell in the container and keeps it open, for a REPL or a database client.
  • shell_input types 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. Set tool_approvals.shell_input to true to be asked about every line.
  • shell_sessions, shell_output and shell_kill list, read and stop this conversation's own sessions, so they never ask.

Conversation helpers

On, and never ask. They act only on the current conversation.

  • ask_user asks 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_write keeps a checklist you can see, for multi-step work.
  • pin keeps the most recent turns word for word when a long conversation is summarised. unpin releases them. Both are limited to this thread and can be undone.
  • load_skill reads the full instructions of a skill listed in the model's prompt. It is offered only when there is a skill to load.

Project documents

  • read_project_doc reads 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, since read is off.
  • write_project_doc always asks. It writes one of the standard documents /init creates (AGENTS.md, ARCHITECTURE.md and so on). It takes a document's name, not a path, so it cannot write anywhere else, but it overwrites that file, and AGENTS.md feeds the instructions of later sessions.

Memory

  • remember always 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>).

Delegation

  • spawn_subagent always 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.

MCP tools

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.

Pre-granting tools for an unattended research run

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 shell decide from each call's arguments, so ticking "shell" would approve commands you never saw; those still ask, or stay hidden.
  • spawn_subagent and remember can never be pre-granted. Approving a spawn signs off the child's whole tool set, and a memory outlives the run.
  • write_project_doc can 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.

What the harness checks on every call

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.