Permissions

​

Permission Modes

​

Mode Cycling

​

Startup Parameters

qoder --permission-mode default
qoder --permission-mode accept_edits
qoder --permission-mode plan           # Legacy compat: translates to default + enters Plan work state
qoder --permission-mode auto
qoder --permission-mode bypass_permissions
qoder --permission-mode yolo           # Equivalent to bypass_permissions
qoder --permission-mode dont_ask

# Shortcuts
qoder --yolo                         # Equivalent to --permission-mode bypass_permissions
qoder --dangerously-skip-permissions # Same as above

# The following are equivalent
qoder --permission-mode bypass_permissions
qoder --permission-mode bypassPermissions
qoder --permission-mode yolo
qoder --yolo
qoder --dangerously-skip-permissions

​

How Decisions Are Made

• allow: Execute the tool immediately.
• ask: Requires external confirmation before execution.
• deny: Block the tool call.

​

Decision Order

1. Check deny rules first — if matched, deny immediately.
2. Tool's own safety checks (e.g., dangerous command detection, sensitive path detection).
3. ask rules — if matched, mark as requiring confirmation.
4. Tool-level allow rules and mode-based auto-allow behavior.
5. If the final result is still ask, the runtime environment determines how to consume it.

​

How ask Is Consumed in Different Environments

# Headless + accept_edits: file edits auto-approved, Bash denied
qoder -p "refactor the utils module" --permission-mode accept_edits

# Headless + bypass_permissions: all allowed (trusted scenarios only)
# Exception: an rm that would remove the working directory, the home directory,
# the root or a top-level directory is denied — nobody can confirm it — unless
# a PermissionRequest hook explicitly allows it
qoder -p "run the migration" --yolo

# Headless + precise allow rules: only specific tools allowed
qoder -p "check status" --allowed-tools 'Read,Bash(git status)'

​

Permission Configuration

​

Configuration Sources (8-Layer Priority)

• Layers 1-3 (settings files): Write permissions.allow / permissions.deny / permissions.ask arrays in the corresponding JSON file. settings.local.json is ideal for machine-local approval rules; add it to .gitignore.
• Layer 4 (flagSettings): qoder --settings ./custom-settings.json specifies an additional settings file. Same format as standard settings.json.
• Layer 5 (cliArg): Configured via --permission-mode, --allowed-tools, --disallowed-tools, --tools CLI arguments; applies to current session only.
• Layer 6 (command): Type /allow Bash(npm test) or /deny WebFetch in-session; persisted to settings.local.json.
• Layer 7 (session): Temporary rules from selecting "Allow for this session" in prompts; lost when the process exits.

​

Mode Configuration

{
  "general": {
    "defaultPermissionMode": "accept_edits"
  }
}

{
  "security": {
    "disableYoloMode": true
  }
}

{
  "general": {
    "plan": {
      "enabled": false
    }
  }
}

{
  "autoMode": {
    "allow": [
      "running npm/yarn/pnpm scripts defined in package.json",
      "creating or editing test files"
    ],
    "soft_deny": [
      "deleting files outside the test directory",
      "modifying CI/CD configuration"
    ],
    "environment": [
      "This is a Node.js monorepo with pnpm workspaces",
      "The project uses Vitest for testing"
    ]
  }
}

• Read-only tools (file reads, search, glob) are approved by tool name. The target path is not evaluated, so paths outside the working directory are approved as well.
• Writes and edits inside the working directory, and inside directories added with /add-dir, are approved directly.
• All other actions are submitted to the classifier, including writes to paths outside those directories.

​

Permission Rule Configuration

{
  "permissions": {
    "allow": [
      "Read(/src/**)",
      "Edit(/src/**)",
      "Bash(npm run test:*)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "WebFetch"
    ],
    "deny": [
      "Read(*.pem)",
      "Bash(rm -rf:*)"
    ]
  }
}

​

Rule Syntax

{
  "permissions": {
    "allow": [
      "Bash(python -c \"print\\(1\\)\")"
    ]
  }
}

​

Command-Line Overrides

qoder --allowed-tools 'Read,Grep,Bash(git status)'
qoder --disallowed-tools 'Bash(rm -rf:*),mcp__github__delete_repo'
qoder --tools 'Read,Grep,Edit'

​

Trust Directories

• File reads are allowed by default
• File writes can be auto-approved in accept_edits and auto modes
• Non-default permission modes (auto, bypass, etc.) are allowed to take effect

​

Extending Trust

qoder --add-dir ../shared

{
  "permissions": {
    "additionalDirectories": ["../shared"]
  }
}

​

Protected Paths

​

Path Shapes

• Network locations — paths beginning with two separators (\server\share, //server/share), extended UNC forms (\?\UNC\server\share), WebDAV spellings, and /net/<host>/… automount paths. On Windows, reading, searching, writing and shell access there ask for confirmation every time. The prompt offers no persistent rule, because a saved rule would permanently authorize disclosing your credentials to that host. A network location may be the working directory or an added directory; startup names it in a warning.
• Local mounts — \wsl$\…, \wsl.localhost\…, \?\C:\… and \?\Volume{…}\… name local storage and follow the normal rules. A loopback host such as \127.0.0.1\share is still a network location.
• Bypass-prone spellings — alternate data streams (file.txt:stream), 8.3 short names (PROGRA~1), device paths (\.\…), trailing dots or spaces, three or more consecutive dots, and reserved device names (CON, NUL, COM1) require explicit approval.

​

File Access Rules

{
  "permissions": {
    "allow": [
      "Read(/src/**)",
      "Edit(/src/**)",
      "Read(~/Documents/specs/**)"
    ],
    "ask": [
      "Edit(/package.json)",
      "Read(~/Downloads/**)"
    ],
    "deny": [
      "Read(*.pem)",
      "Edit(/.git/**)",
      "Edit(//etc/**)"
    ]
  }
}

​

Bash Rules

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git log:*)",
      "Bash(npm run test:*)"
    ],
    "ask": [
      "Bash(npm publish:*)",
      "Bash(git push:*)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)"
    ]
  }
}

• deny and ask rules see through common wrappers and environment variable prefixes, so Bash(rm -rf:*) still catches wrapped destructive commands.
• Prefix and wildcard allow rules do not silently approve compound commands unless every top-level command segment is independently allowed.
• Some provably read-only shell commands can be automatically allowed after deny, ask, and path checks.
• Dangerous commands (destructive deletes, force pushes) can still force confirmation even with broad allow rules.

​

Web and MCP Rules

{
  "permissions": {
    "ask": [
      "WebFetch"
    ],
    "deny": [
      "WebSearch"
    ]
  }
}

mcp__<server>__<tool>

{
  "permissions": {
    "allow": [
      "mcp__context7__*"
    ],
    "ask": [
      "mcp__github__create_issue"
    ]
  }
}

qoder --allowed-mcp-server-names context7,github

​

Subagent Rules

{
  "permissions": {
    "allow": [
      "Agent(explore)"
    ],
    "ask": [
      "Agent(deploy-helper)"
    ],
    "deny": [
      "Agent(code-review)"
    ]
  }
}

• A matching deny rule blocks the launch.
• A matching ask rule shows a confirmation prompt before the Subagent starts.
• A matching allow rule explicitly records the approval; the outcome is the same as having no rule.

​

Hooks and Permissions

​

Hook Events That Affect Permissions

​

PreToolUse Hook

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python ./scripts/check-bash-command.py"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Command blocked by security policy"
  }
}

• "allow": Skip permission pipeline, approve directly
• "deny": Skip permission pipeline, deny directly
• "ask": Continue through normal permission pipeline (default behavior)

​

PermissionRequest Hook

{
  "hooks": {
    "PermissionRequest": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "node ./scripts/auto-approve-safe-ops.js"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {},
      "updatedPermissions": []
    }
  }
}

​

Hook Priority vs. Permission Modes

1. Hook PreToolUse → if returns allow/deny, short-circuit
2. Permission pipeline (rules + mode + safety checks)
3. If result is ask → Hook PermissionRequest → if returns allow/deny, short-circuit
4. Finally, the runtime environment consumes ask (prompt/deny/callback)