23. Permissions & safety#
RayuCode v3 does not show a per-tool approval prompt during an interactive session. The model reads, edits and runs commands without asking. What protects you instead is a small set of deterministic gates, plus the fact that every change is visible in the transcript and reversible through git.
This page explains what actually runs, and what to do when you want stricter control.
What asks, and what does not#
| Action | Behaviour in v3 |
|---|---|
| Reading files, searching, listing | Runs immediately |
| Editing or writing files | Runs immediately, diff shown inline |
| Running a shell command | Runs immediately, unless the destructive-command gate stops it |
| Fetching a URL or searching the web | Runs immediately |
| Calling an MCP tool | Runs immediately |
| Ambient-mode actions that leave the sandbox | Requires approval (rayu permissions) |
| Telegram remote tool approvals | Cards in the chat, when configured |
There is no default / acceptEdits / plan / bypassPermissions mode cycle
and no --permission-mode flag. Shift+Tab cycles favorite models.
The destructive-command gate#
Before bash runs, Rayu classifies the command by blast radius, not by name:
what it would destroy, and whether that can be undone.
| Risk | Example | Result |
|---|---|---|
| Safe | ls, cargo test, git status | Runs immediately |
| Low | A destructive command confined to the working directory or a temp dir | Runs, logged |
| Confirm | Destructive target cannot be determined statically | Held until the model re-justifies it against your actual request |
| Catastrophic | rm -rf ~, /, device nodes, credential stores | Never runs, no justification unlocks it |
The model has a justification field on the bash tool for the Confirm tier.
If it cannot give a reason tied to your request, the command does not run. That
is why you may see the model restate why a command is safe before it fires.
This is defence in depth, not a sandbox. A deliberately obfuscated command
(sh -c "$(printf …)") can defeat any static parser, which is why the gate is a
reflection prompt in the middle tier and a hard deny only for the small, absolute,
path-based catastrophic tier.
Making it stricter: the pre_tool hook#
A pre_tool hook is the general-purpose gate. It runs before every tool call
with the tool name and input, and its exit code decides:
| Exit code | Effect |
|---|---|
0 | Allow |
2 | Block; stderr is fed back to the model |
| anything else | Fail open (the tool runs) |
# ~/.rayu/config.toml
[hooks]
pre_tool = "~/bin/rayu-tool-policy"The hook receives the tool input JSON on stdin as well as in
RAYU_HOOK_TOOL_INPUT, which is why the snippet above reads jq from stdin.
See Hooks for the full variable list and the transform and feedback hooks.
Narrowing the tool set#
You can remove tools entirely instead of gating them:
rayu --tool-profile minimal # a small read/edit/run set
rayu --tools read,agentgrep,edit # explicit allow-list
rayu --disabled-tools bash,write # hide specific tools
rayu --disable-base-tools # nothing unless opted back inThe same settings persist in [tools]:
[tools]
profile = "minimal"
disabled = ["bash"]A session with no bash tool cannot run shell commands at all. That is stronger
than any prompt.
Plan-first work#
/plan [goal] asks the model for a plan-only proposal rendered as a plan card,
with no edits. Once you approve it, work proceeds normally. /effort swarm
additionally spreads implementation across workers.
Because there is no "plan mode" gate on the tools themselves, /plan is a
request, not an enforcement boundary. If you need enforcement, use [tools]
profiles or a pre_tool hook.
Ambient mode approvals#
Ambient mode is the one place v3 asks for permission. An ambient agent that wants
to do anything that communicates with another human or leaves the local sandbox
calls request_permission and waits.
Review those requests:
rayu permissionsInside a session, the pending request appears in the TUI review panel. Approve, deny, or answer the question. The agent proceeds or moves on based on your answer.
The rules: anything that sends a message, opens a PR, pushes, or otherwise leaves a trace outside your checkout needs approval. Anything local and reversible does not.
Telegram approvals#
If you drive a session from Telegram, tool use that needs a decision can arrive as a card with inline buttons, mirroring what the terminal would ask. The transport is the same engine, so the answer applies to the running session. See Telegram bot.
Working safely#
- Keep the repository under version control.
git diffis the real audit trail. - Review edits as they stream; the diff is inline by default
(
[display] diff_mode). - Use
[tools]profiles in untrusted repositories rather than relying on judgement. - Add a
pre_toolhook when a project has commands that must never run. - Run untrusted code in a container. No in-process gate substitutes for that.
Next: Sessions & checkpoints →