Rook Permissions and Safety
Rook's internal roles can call tools while discovering, generating, invoking, and verifying. Every call must be covered by a rule or approved through an interactive prompt.
Read an Interactive Permission Prompt
In the TUI, inspect the tool, exact file or target, and requested operation before approving. This real prompt occurs while Rook authors the quickstart's local-triage profile; it asks to write that profile's hook script, not to run a test suite:
Use the arrow keys to select and Enter to answer. yes approves that action once; no declines it. Read the hint beside always: for a model-chosen action such as the one pictured, it allows the matching operation for this run without writing a disk grant. A persistent choice on a human-requested action has a different scope. never can save a denial. Do not choose a broad option merely to clear the prompt.
After approval, watch the next operation and its result. A permission prompt or a generated file is not proof that the target was reached or that a scenario passed.
Rule Grammar
Rules identify the tool and the allowed subject:
Verifiedbash(npm test) exact command
bash(git *) glob over the command
read_file(.) any file below the current path
mcp_start(payments) one named MCP server
mcp_call(billing.lookup) one server tool
Add @phase to limit a grant to one phase:
bash(git *)@explore
read_file(.)@generate
Why Rules Are Phase-Scoped
Approving bash(git *) while Rook explores a repository does not imply that the same operation should be allowed while judging an adversarial target. The operator is authorizing work in the context they can see—exploration, generation, execution, or judging—not an internal role name that may be difficult to reason about.
Use the narrowest subject and phase that covers the intended operation.
Permission Lists
| List | Applies to | How it is written |
|---|---|---|
allow | Actions explicitly requested or approved by a person | Selecting a persistent “always” choice at an interactive prompt |
deny | Human-requested and model-selected actions, always | Edited by the user or administrator |
autonomous | Model-selected actions during unattended work | Only by deliberate file editing or a reviewed launch grant |
Rook does not promote an interactive “always” response into unattended authority. A choice made during a terminal session should not silently become the permission model for the next CI run.
--yes and --allow
These flags solve different problems:
| Flag | Scope | Persistence |
|---|---|---|
--yes | Approves tool calls for the current command | Writes nothing to settings |
--allow <rule> | Supplies one explicit rule to the current process; repeatable | Visible in the launch command or pipeline definition |
rook explore . \
--allow 'bash(npm test)' \
--allow 'bash(git *)@explore'
rook run --yes
For CI, prefer reviewed --allow rules so authority is visible beside the job definition. Use --yes only when blanket approval for that command is intentional.
The Target Agent Is Real
Rook invokes the target exactly as a user would. Files, refunds, tickets, messages, database changes, deployments, and other writes can be real.
Before a run, Rook reports declared write tools and asks for approval. Approval is per target so a decision for one agent is not inherited by another.
Use:
- staging or isolated targets;
- disposable accounts and fixtures;
- read-only credentials where possible;
--concurrency 1until shared-state behavior is understood;- explicit cleanup hooks for resources the scenario creates;
- narrow permissions for verification tools.
Verification Should Not Create State
A judge is instructed to verify without changing the system. For example, calling issue_refund to see whether a refund exists would create the refund and invalidate the check. Provide a read endpoint, trace, filesystem observation, or read-only MCP tool instead.
Every verification tool call still passes through the same permission gate. Enabling an MCP server does not automatically authorize every tool it exposes.
Headless Mode
Rook enters headless mode when any of these are true:
--yesis present;- standard input is not a TTY;
- a recognized runner variable is present:
CI,GITHUB_ACTIONS,GITLAB_CI,BUILDKITE, orJENKINS_URL.
In headless mode, an operation not covered by an existing rule is refused with a reason instead of waiting for a prompt no one can answer.
Future Mediated Execution
The current model directly invokes your agent. A mediated mode in which Rook hosts agent tools and can virtualize writes is planned; do not assume that protection exists in current runs.
Review Without Re-Executing
Both the local UI (rook ui --local) and hosted Web UI (rook ui) are read-only review surfaces. Opening a result does not run the target, grant hook permissions, or approve a verifier. Local review reads workspace files; hosted review reads uploaded records and requires project access.
Read-only viewing does not make captured data safe to share. Inspect requests, responses, and artifacts for secrets and customer data, and treat agent-produced files as untrusted. Use authorized hosted links or approved evidence bundles, never a publicly exposed loopback server. See the combined UI guide.
Local UI: Review Observed Effects
Open agent → Runs → run → scenario to inspect what the evidence says happened. This CommerceCare result distinguishes a failed response requirement from two unverifiable tool/state assertions. Missing evidence does not prove that an action was blocked or never happened. Neither viewer grants permission or undoes the target's writes. See the local UI rollout note if your screen differs.
Hosted Web UI: Identify Write-Capable Tools
Open Versions → View call graph. The graph marks declared read-only and write-capable tools. These relationships describe capability, not actual execution or permission grants. Neither UI edits permission rules; review and approve operations through the CLI.
Chat with Us