# 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:

Mode | Behavior
--- | ---
`default` | Ask before sensitive tool actions (read/write/bash/network). Safe default.
`ask` | Always ask before any tool execution.
`plan` | Prefer planning mode — AI must present a plan before executing tools.
`auto` | Auto-approve low-risk actions using transcript classifier (requires `TRANSCRIPT_CLASSIFIER` feature). Prompt for risky operations.
`acceptEdits` | Auto-approve file edit operations. Useful for rapid iteration.
`bypassPermissions` | Skip all permission prompts. Use only in trusted sandboxes.
`dontAsk` | Never 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

Flag | Description
--- | ---
`--permission-mode <mode>` | Set session permission mode
`--dangerously-skip-permissions` | Bypass all checks (sandbox only)
`--allow-dangerously-skip-permissions` | Enable 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.