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.
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 → run → scenario to inspect what the evidence says happened. The sample criterion quotes an observed set_severity call. This is evidence from a completed test, not a UI for granting permission or undoing the target's write.
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