Permissions

Control which tools can execute automatically, require confirmation, or are blocked entirely.

Overview

Permissions provide fine-grained control over tool execution. You can configure which tools are auto-approved (run without asking), which require user confirmation, and which are completely blocked.

Safety Modes

Every session runs in a safety mode that decides what happens when no permission rule matched a tool call. The runtime labels each call safe (safe-listed shell command such as ls or git status, or a read-only-annotated tool), destructive (destructive shell command such as rm -rf, or a destructive-annotated tool), or unknown — and the mode gates on that label. Command classification applies to both shell and run_background_job:

• strict prompts for every tool call, read-only ones included. Only an allow: rule silences a prompt.
• balanced runs safe calls silently and asks about everything else.
• restricted is the fail-closed profile for unattended/headless runs: safe calls run silently and everything else is denied without asking — the mode's fallback never prompts. Custom rules still win: an allow: rule can approve a destructive/unknown call, a deny: rule always blocks, and session-scoped ask: rules still prompt (as can a preempt_yolo hook). Restricted is defense in depth against unwanted tool calls, not a security boundary — for real isolation use sandbox mode.
• autonomous is the legacy --yolo behavior: everything runs. Only deny: rules, session-scoped ask: rules, tool_guard, and preempt_yolo hooks still gate.

Pick a mode with the --safety flag (docker-agent run --safety balanced ...), the safety_policy field on session create (POST /api/sessions) or mid-session (PATCH /api/sessions/:id/safety-policy), or escalate directly from a confirmation prompt (B switches to balanced, A to autonomous; the restricted fallback never prompts, so the mode is only selected via flag/config/API). Sessions that never choose a mode keep the historical default: read-only tools auto-approve, everything else asks.

Declarative Safety Defaults

Safety modes can also be declared as defaults in YAML, at four scopes:

# Agent YAML (author-declared defaults)
runtime:
  safety: balanced # config-wide default for new sessions

agents:
  root:
    safety: strict # overrides runtime.safety for this agent

All four fields accept only the four canonical modes — strict, balanced, restricted, autonomous (yes, an author may declare autonomous) — and any other value fails loading with an error naming the field. The legacy spellings remain as aliases for autonomous: settings.YOLO, the alias yolo option, and the --yolo flag. When both are set at the same scope, safety wins over the legacy YOLO/yolo.

For a new root session the first source in this order wins:

1. explicit --safety flag
2. explicit --yolo flag
3. alias safety/yolo option
4. settings.safety/settings.YOLO (user config)
5. selected agent's agents.<name>.safety
6. runtime.safety
7. the historical default (read-only tools auto-approve, everything else asks)

Resuming a session never re-applies defaults: the stored mode is kept unless you pass an explicit --safety or --yolo flag for that run. Agent switches, handoffs, and delegated sub-agent sessions inherit the active session's mode rather than resetting it.

Sessions created through the API (POST /api/sessions) without a safety_policy receive the author-declared defaults (5–6) when their first run starts — the earliest point the agent configuration is loaded. If the server restarts before that first run, the session keeps the historical unset default (7).

Custom rules always win over the mode, with one asymmetry: ask: rules written in an agent's YAML (or global config) are agent-author advisories and yield to a user-chosen balanced/restricted/autonomous mode (under restricted they resolve to the mode's allow-or-deny verdict rather than introducing a prompt), while ask: rules granted at the session level (interactive "always ask" decisions, the session permissions API) always prompt.

Permission Levels

Permissions can be defined at two levels:

Hooks follow the same user-config pattern: agent-level hooks live under agents.<name>.hooks, and global hooks live under settings.hooks. See Hooks.

Both levels use the same allow/ask/deny pattern syntax. When both are present, they are merged at startup -- patterns from both sources are combined into a single checker. See Merging Behavior for details.

Agent-Level Configuration

agents:
  root:
    model: openai/gpt-4o
    description: Agent with permission controls
    instruction: You are a helpful assistant.

permissions:
  # Auto-approve these tools (no confirmation needed)
  allow:
    - "read_file"
    - "read_*" # Glob patterns
    - "shell:cmd=ls*" # With argument matching

  # Ask when no deny or allow pattern matches (subject to the safety mode)
  ask:
    - "shell:cmd=git push*"
    - "write_file:path=/home/user/important/*"

  # Block these tools entirely
  deny:
    - "shell:cmd=sudo*"
    - "shell:cmd=rm*-rf*"
    - "dangerous_tool"

The three lists are evaluated in order deny → allow → ask. An ask: entry does not override a matching allow rule; narrow or remove the allow rule where confirmation is required. Team-level asks also yield to the active safety mode as described above.

Global Permissions

Global permissions let you enforce rules across all agents, regardless of which agent config you run. Define them in your user config file:

# ~/.config/cagent/config.yaml
settings:
  permissions:
    deny:
      - "shell:cmd=sudo*"
      - "shell:cmd=rm*-rf*"
    allow:
      - "read_*"
      - "shell:cmd=ls*"
      - "shell:cmd=cat*"

This is useful for setting personal safety guardrails that apply everywhere -- for example, always blocking sudo or always auto-approving read-only tools -- without relying on each agent config to include those rules.

Merging Behavior

When both global and agent-level permissions are present, they are merged into a single set of patterns before evaluation. The merge works as follows:

• Deny patterns from either source block the tool. A global deny cannot be overridden by an agent-level allow, and vice versa.
• Allow patterns from either source auto-approve the tool (as long as no deny pattern matches).
• Ask patterns from either source are considered only when no deny or allow pattern matches. They prompt in strict or legacy mode, but yield when the active mode is balanced, restricted, or autonomous.

The evaluation order remains the same after merging: Deny > Allow > Ask > safety-mode fallback.

Pattern Syntax

Permissions support glob-style patterns with optional argument matching:

Simple Patterns

Argument Matching

You can match tools based on their argument values using tool:arg=pattern syntax:

permissions:
  allow:
    # Allow shell only when cmd starts with "ls" or "cat"
    - "shell:cmd=ls*"
    - "shell:cmd=cat*"

    # Allow edit_file only in specific directory
    - "edit_file:path=/home/user/safe/*"

  deny:
    # Block shell with sudo
    - "shell:cmd=sudo*"

    # Block writes to system directories
    - "write_file:path=/etc/*"
    - "write_file:path=/usr/*"

Multiple Argument Conditions

Chain multiple argument conditions with colons. All conditions must match:

permissions:
  allow:
    # Allow shell with ls in current directory
    - "shell:cmd=ls*:cwd=."

  deny:
    # Block shell with rm -rf anywhere
    - "shell:cmd=rm*:cmd=*-rf*"

Glob Pattern Rules

Patterns follow filepath.Match semantics with some extensions:

• * — matches any sequence of characters (including spaces)
• ? — matches any single character
• [abc] — matches any character in the set
• [a-z] — matches any character in the range

Matching is case-insensitive.

Decision Types

Examples

Read-Only Agent

Allow all read operations, block all writes:

permissions:
  allow:
    - "read_file"
    - "read_multiple_files"
    - "list_directory"
    - "directory_tree"
    - "search_files_content"
  deny:
    - "write_file"
    - "edit_file"
    - "shell"

Safe Shell Agent

Allow specific safe commands, block dangerous ones:

permissions:
  allow:
    - "shell:cmd=ls*"
    - "shell:cmd=cat*"
    - "shell:cmd=grep*"
    - "shell:cmd=find*"
    - "shell:cmd=head*"
    - "shell:cmd=tail*"
    - "shell:cmd=wc*"
  deny:
    - "shell:cmd=sudo*"
    - "shell:cmd=rm*"
    - "shell:cmd=mv*"
    - "shell:cmd=chmod*"
    - "shell:cmd=chown*"

MCP Tool Permissions

Control MCP tools by their qualified names:

permissions:
  allow:
    # Allow all GitHub read operations
    - "github_get_*"
    - "github_list_*"
    - "github_search_*"
  deny:
    # Block destructive GitHub operations
    - "github_delete_*"
    - "github_close_*"

Combining with Hooks

Permissions work alongside hooks. The evaluation order is:

1. Run tool_input_transform hooks — patch arguments before classification, guards, or permission checks
2. Run tool_guard hooks — mandatory checks; deny is terminal and ask requires fresh confirmation (unless policy denies the call)
3. Run preempt_yolo pre_tool_use hooks — legacy mandatory checks, with their existing session-grant exception
4. Check deny patterns — if matched, tool is blocked
5. Check allow patterns — if matched, tool is auto-approved
6. Check ask patterns — if matched, the user is prompted directly, skipping the default pre_tool_use lane
7. If no rule matched, apply the safety mode to the call's safety label — may auto-approve (or, under restricted, deny)
8. On a mode "ask", run pre_tool_use hooks — hooks can allow, deny, or ask
9. If no decision, ask user for confirmation

Default-lane hooks only see calls the mode routed to "ask"; they cannot override deny decisions or explicit ask: rules. If they rewrite arguments, mandatory checks and permission rules are evaluated again before execution. A new ask during this recheck requires fresh confirmation; earlier grants cannot bypass it. See tool phases.