Permissions

Ripperdoc includes a permission system to protect against unintended operations.

How Permissions Work

By default, Ripperdoc prompts for approval before:

• Executing shell commands
• Editing or writing files
• Running potentially destructive operations

When a permission prompt appears, you can:

• y/yes: Allow the operation
• n/no: Deny the operation
• a/always: Always allow this type of operation
• Esc: Deny the operation

The permission prompt interface uses Rich Panel for better visual consistency. For Bash tools, it displays complete command details (including timeout, sandbox, etc.) for security review.

Session-Level Permissions

In addition to persistent rules in configuration files, Ripperdoc also supports session-level permission management:

• session_allowed_tools: List of tools allowed during the session
• session_tool_rules: Tool rules for the session (e.g., bash command patterns)

These settings are cleared when the session ends and are not persisted. When you choose the "2/s" (allow for session) option, the corresponding tool or command rules are added to session-level permissions.

YOLO Mode

Skip all permission prompts with YOLO mode:

ripperdoc --yolo

Warning: Use YOLO mode only in trusted environments where you're comfortable with the AI making changes without confirmation.

Permission Configuration

Permissions are configured in project-level files:

1. .ripperdoc/config.json - Main project configuration
2. .ripperdoc/config.local.json - Local overrides (gitignored)

Configuration Schema

{
  "allowed_tools": ["Read", "Glob", "Grep", "LS", "Edit", "Bash"],
  "working_directories": ["/path/to/allowed/dir"],
  "bash_allow_rules": [
    {
      "pattern": "npm test",
      "description": "Allow running tests"
    },
    {
      "pattern": "git status",
      "description": "Allow git status"
    }
  ],
  "bash_ask_rules": [
    {
      "pattern": "terraform *",
      "description": "Always ask before terraform"
    }
  ],
  "bash_deny_rules": [
    {
      "pattern": "rm -rf /",
      "description": "Prevent destructive commands"
    }
  ]
}

Configuration Fields

Rule Pattern Syntax

Rules use glob-style patterns:

• npm test - Exact match
• npm * - Prefix match
• *test* - Contains match
• git @(status|diff|log) - Multiple alternatives

Rule Precedence

When multiple rules match, precedence is:

1. deny
2. ask
3. allow

Example Configurations

Development Project

{
  "allowed_tools": ["Read", "Glob", "Grep", "LS", "Edit", "Write", "Bash"],
  "working_directories": ["."],
  "bash_allow_rules": [
    {"pattern": "npm *", "description": "Allow npm commands"},
    {"pattern": "git *", "description": "Allow git commands"},
    {"pattern": "python *", "description": "Allow python commands"}
  ],
  "bash_deny_rules": [
    {"pattern": "rm -rf /*", "description": "Prevent recursive delete from root"}
  ]
}

Read-Only Analysis

{
  "allowed_tools": ["Read", "Glob", "Grep", "LS"],
  "bash_allow_rules": [
    {"pattern": "ls *", "description": "Allow listing"},
    {"pattern": "cat *", "description": "Allow reading"}
  ]
}

Read-Only Operations

Some operations are automatically allowed as read-only:

• Glob - Finding files
• Grep - Searching content
• Read - Reading files
• LS - Listing directories
• Shell commands: ls, cat, head, tail, grep, find (without redirects)

Sandbox Mode

The Bash tool supports sandbox mode for read-only shell operations:

{
  "command": "ls -la",
  "sandbox": true
}

Sandbox mode:

• Prevents filesystem writes
• Blocks network access
• Runs without permission prompts

Working with Sensitive Directories

Ripperdoc will prompt for confirmation when accessing sensitive directories:

• /usr, /etc, /bin, /sbin
• System configuration directories
• Other user home directories

Managing Permissions

Use the /permissions command to view and manage permissions (interactive UI when available):

> /permissions
> /permissions tui
> /permissions list
> /permissions add allow Bash "npm *"
> /permissions add ask Bash "terraform *"
> /permissions remove local ask "terraform *"

Local Configuration Override

Use .ripperdoc/config.local.json for local-only settings that shouldn't be committed:

{
  "bash_allow_rules": [
    {"pattern": "docker *", "description": "Local docker access"}
  ],
  "bash_ask_rules": [
    {"pattern": "kubectl *", "description": "Always ask before kubectl"}
  ]
}

Add .ripperdoc/config.local.json to your .gitignore.

Tool Custom Permission Checks

Tools can implement custom check_permissions methods to override default permission behavior. This method receives the tool input and permission context, returning a PermissionDecision object.

from ripperdoc.utils.permissions import PermissionDecision, ToolRule

def check_permissions(self, parsed_input, context):
    """Custom permission check logic.

    Args:
        parsed_input: Parsed tool input
        context: Dictionary with allowed_rules, denied_rules, allowed_working_directories

    Returns:
        PermissionDecision object with behavior, message, rule_suggestions
    """
    allowed_rules = context.get("allowed_rules", set())
    denied_rules = context.get("denied_rules", set())

    # Return decision
    return PermissionDecision(
        behavior="allow",  # allow, deny, ask, passthrough
        message="Custom permission check result",
        rule_suggestions=[ToolRule(tool_name="ToolName", rule_content="pattern")],
        updated_input=parsed_input  # Optional: modified input
    )

Supported behavior types:

• allow: Auto-approve the operation
• deny: Auto-deny the operation
• ask: Ask user for confirmation
• passthrough: Use default behavior (typically ask)

Best Practices

1. Start with defaults: Use the default permission system until you understand your workflow
2. Allow specific commands: Create allow rules for frequently used safe commands
3. Deny dangerous patterns: Explicitly deny patterns like rm -rf /
4. Use ask rules for risky tools: Require confirmation for sensitive commands
5. Use sandbox for exploration: Use sandbox mode when exploring unfamiliar codebases
6. Review before YOLO: Only use YOLO mode after reviewing what Ripperdoc will do
7. Use local config: Put personal/machine-specific rules in config.local.json