Home/Permission Model

Permission Model

Clew gates tool execution through a tiered permission system with multiple modes, allow/deny rules, and tool-specific checks.

Permission Modes

Defined in src/types/permissions.ts. Seven user-addressable modes:

ModeBehavior
defaultAsk before sensitive tool actions (read/write/bash/network). Safe default.
askAlways ask before any tool execution.
planPrefer planning mode — AI must present a plan before executing tools.
autoAuto-approve low-risk actions using transcript classifier (requires TRANSCRIPT_CLASSIFIER feature). Prompt for risky operations.
acceptEditsAuto-approve file edit operations. Useful for rapid iteration.
bypassPermissionsSkip all permission prompts. Use only in trusted sandboxes.
dontAskNever ask — auto-deny anything that would require permission.

Permission Rules

Granular allow/deny rules control specific tools and their arguments:

/permissions     # Open interactive permission rule manager

Rules can target specific tools with pattern matching:

  • Bash(git *) — Allow/deny git commands specifically
  • Edit — Allow/deny all file edits
  • Bash(rm *) — Warn/block destructive shell commands

Rule Sources

Permission rules come from multiple sources (evaluated in order, with later sources overriding earlier ones):

  • userSettings — From user config file
  • projectSettings — From project-level settings
  • localSettings — Local overrides
  • flagSettings — From CLI flags (--allowedTools, --disallowedTools)
  • policySettings — Managed/organization policy

Tool Permission Flow

1. Tool input validation (validateInput)
2. Tool-specific checkPermissions()
3. Deny rule check (permissions.ts getDenyRuleForTool)
4. Permission mode evaluation (mode-based auto decision)
5. Plugin hooks (PreToolUse PostToolUse)
6. Classifier-based auto-approval (auto mode)
7. User permission dialog (if needed)

CLI Flags for Permissions

FlagDescription
--permission-mode <mode>Set session permission mode
--dangerously-skip-permissionsBypass all checks (sandbox only)
--allow-dangerously-skip-permissionsEnable bypass as optional mode
--allowedTools, --allowed-tools <tools...>Allowlist specific tools with patterns
--disallowedTools, --disallowed-tools <tools...>Denylist specific tools with patterns

Security Best Practices

  • Default mode for day-to-day development
  • Plan mode for production infrastructure or unfamiliar code
  • Bypass modes only in disposable worktrees or Docker sandboxes
  • Use allow/deny rules to permit safe patterns (e.g., Bash(git *)) while blocking dangerous ones
  • Run /doctor to audit current permission settings
Use Caution bypassPermissions mode executes all tool actions without prompting. Restrict to trusted, sandboxed environments.