Skip to content

Configure guardrails

This guide shows you how to configure guardrails: the rules that decide whether an agent’s action runs, asks for approval first, or is refused.

Guardrails cover the fourteen effect classes every mutating tool declares. They are enforced server-side at the point the tool is called, never by an instruction in a prompt.

  1. Go to Settings → Workspace → Agent permissions
  2. Pick a scope with the segmented control: Workspace, Agent (then choose the agent), or Space (then choose the space)
  3. On the row for the action class, pick Allow, Ask first or Deny
  4. To drop a rule you set, press the reset button that appears at the end of that row (Clear to inherited) — the decision falls back to the wider scope

Each row shows the action’s setting as a status tag and a badge for where it came from: This scope, Inherited or Built-in default. The matrix resolves at Agent (chat) mode, so Mode preset never appears here — use the what-if probe with a read-only mode selected to see that layer.

Writing a rule needs the admin role. Reading the matrix does not.

Checkpoint: set Push to a remote to Deny at the workspace scope, then run the what-if probe below on git push origin main. The result reads deny with source workspace.

Answering an approval card with Approve for 8 hours writes a standing approval: a rule that lets the same kind of action through without asking until it ends. Each one is listed on this page, under the action it belongs to.

  1. Go to Settings → Workspace → Agent permissions and pick the scope. An approval is written for the space the question came from, so pick Space and then that space
  2. Under the action’s row, read the entry: what it allows (for example, pushes to branches matching feature/**), the words Standing approval, who gave it when that was someone else, and when it ends
  3. To end it now, point at the entry and press Revoke. Agents ask again from their next action on

The row keeps showing the action’s own setting, and a line under it counts the cases listed below that are allowed anyway. Conditional rules that a template wrote appear in the same list, and command rules in a Commands group after the last action. At the workspace scope, a note under the summary counts the standing approvals set for single spaces or agents. At a space or agent, it counts the workspace’s, which apply there too.

A standing approval only spares a question. It never overrides Deny: if you set an action to Deny while one is running, its entry reads not in effect while denied until it ends or you revoke it. Changing an action’s setting leaves its standing approvals in place, and revoking one leaves the setting.

Resolution is specificity first, then restrictiveness:

  1. Space rules, then agent, then workspace. The first scope with a matching rule decides and resolution stops
  2. If no rule matches, the mode preset applies — a read-only mode (plan, review, orchestrate) refuses twelve of the fourteen classes
  3. If the mode has nothing to say, the built-in default applies

Within a single scope, a command rule resolves by longest matching prefix and an equally specific conflict resolves most restrictive — deny beats ask first beats allow. An action that declares several classes resolves each one independently and then combines them most-restrictive.

An Ask first decision surfaces one approval prompt covering every class that resolved to prompt. With no approver connected it is denied, for both shell commands and harness tool calls. That is deliberate: an ungated run is worse than a refused one.

Action class Built-in default
Delete a file Ask first
Write outside the worktree Allow
Create a commit Allow
Push to a remote Ask first
Open a pull request Ask first
Update or merge a pull request Ask first
Write to an external tracker Ask first
Access the network Allow
Read a secret Allow
Install a package Allow
Run a process Allow
Change workspace structure Allow
Drive an enclosure (rig) Allow
Run commands on the host Ask first

The taxonomy is closed. A new tool that ships without declaring its classes fails a ratchet test in CI, so nothing arrives with a silently empty effect set.

Before changing a rule, check how the current policy already resolves it.

  1. On the same page, scroll to What if?
  2. Pick an Action (one of the fourteen classes)
  3. Optionally fill in Command (for example git push origin main), Agent, Space and Mode
  4. Read the result: the decision, the reason and Source:

The probe runs the same resolver the enforcement path uses, against your live rules, so the answer is exact. When a standing approval decides, the source reads Standing approval followed by its scope. If the answer surprises you, change a rule in the matrix above and probe again.

The dial is per agent per space and it composes with the rules rather than replacing them.

  1. Open the space
  2. Open Manage participants from the space header
  3. Under Autonomy on the agent’s row, pick a level:
Level Effect
Default No space setting — behaves as Act with approval
Propose only Every gated tool is denied outright, with a message telling the agent to propose the action instead
Act with approval Risky actions hit the fail-closed approval gate
Act freely Pre-approves anything that did not resolve to a hard deny

The dial only reaches the built-in harness. The Claude Code adapter runs its own tools outside this gate.

The Where rules are enforced table at the bottom of the same page is the in-app version of this: per effect class, it says whether each runner catches it at the policy gate, leaves it to the sandbox, or cannot intercept it at all.

  • The Claude Code adapter is only partly gated on its own tool calls. Claude Code is launched with --dangerously-skip-permissions, so its read, write and edit calls never pass through the guard. Its bash commands reach the guard through a hook that classifies the command line, and its pushes go through the push gateway like every agent’s. The MCP tool surface it calls back into and the shell command Control Center spawns to launch it are gated too.
  • A mode’s own output verb (submit_plan, propose_orchestration) is pinned and can never be denied — otherwise a mode would be structurally unable to produce its only deliverable.
  • Whether the sandbox backs these rules up depends on the host. Where cc_server finds a backend it wraps the Claude Code CLI and the harness bash tool, so a rule you did not write still has an OS floor under it. On Windows there is none and on Linux or WSL2 without bwrap and socat there is none either — there, guardrails plus the mode’s tool surface are the whole enforcement, not a second line of it. Check which case you are in with Configure sandbox policies.