---
name: permissions-help
description: Explain or troubleshoot the Yes-Claude plugin. Use when the user asks why they got prompted (or were auto-allowed/denied), how to change permission rules, what a category does, or how to write allow/deny patterns. Also use when the user wants to install or migrate this plugin to a new machine.
---

You help the user understand and configure the `yes-claude` plugin.

## What it does

The plugin runs a PreToolUse hook before every tool call. The hook reads a TOML config and returns one of:
- `allow` → tool call runs without prompting
- `ask`   → the normal Claude Code permission prompt appears
- `deny`  → the tool call is blocked

## Config location (first existing wins)

1. `$CWD/.claude/yes-claude.toml`  (project override)
2. `~/.claude/yes-claude.toml`     (user-global)
3. `${CLAUDE_PLUGIN_ROOT}config/permissions.default.toml` (shipped fallback — "ask everything")

## Categories

Every tool call is mapped to one category. The categories are:

| Category | Tools it covers |
|---|---|
| `read_files`        | `Read`, `Glob`, `Grep`, `NotebookRead`, `LS` |
| `edit_files`        | `Edit`, `Write`, `NotebookEdit`, `MultiEdit` |
| `shell`             | `Bash`, non-destructive, non-git commands |
| `shell_destructive` | `Bash` matching `sudo`, `rm -r`, `dd`, `mkfs`, pipe-to-shell, fork bomb, etc. |
| `network`           | `WebFetch`, `WebSearch` |
| `git_safe`          | `git status/log/diff/branch/show/blame`, `gh ... view/list`, `gh api` |
| `git_write`         | `git commit/push/pull/merge/tag/stash/rebase`, `gh pr create`, etc. |
| `git_destructive`   | `git push --force`, `git reset --hard`, `git branch -D`, `git clean -f`, `git checkout .` |
| `subagents`         | `Agent`, `Task` |
| `mcp`               | any `mcp__*` tool |
| `scheduling`        | `CronCreate`, `CronDelete`, `CronList`, `ScheduleWakeup` |

## Modes per category

- `mode = "allow"`  auto-approve
- `mode = "ask"`    show the normal prompt
- `mode = "deny"`   block
- `mode = "custom"` consult `allow` / `deny` pattern lists for this category; if no pattern matches, fall back to the global `default`

## Pattern syntax

- **Shell commands** (`shell`, `shell_destructive`, `git_*`): glob with `*` matching any sequence. Example: `"git *"`, `"rm -rf *"`.
- **File paths** (`read_files`, `edit_files`): glob with `**` matching any depth, `*` matching one path segment. Tilde is expanded. Example: `"~/Desktop/**"`, `"**/.env"`.
- **Domains** (`network.allow_domains`): exact or wildcard subdomain. Example: `"github.com"`, `"*.anthropic.com"`.

## Evaluation order inside a `custom` category

1. `deny` patterns — first match blocks.
2. `allow` patterns — first match approves.
3. (For `network` only) `allow_domains` — first match approves.
4. Fall through to the global `default`.

## When the user asks "why was I prompted for X?"

1. Identify what tool call X corresponds to and run it through `categorize()` in your head (see the table above).
2. Read the active config and report the matching rule.
3. If they want it auto-allowed, suggest the smallest change — adding to the category's `allow` list, or switching the category's `mode`.
4. Note that config edits are live — they apply on the next tool call, no restart needed. (Restart is only required the first time the plugin is installed.)

## Useful slash commands

- `/yes-claude:perm-mode <allow-everything|allow-most|allow-cautious|ask|example>` — switch preset
- `/yes-claude:perm-edit` — open the config in $EDITOR
- `/yes-claude:perm-status [command]` — show the active config; with an argument, dry-run the hook against that command

## Presets at a glance

| Preset | Categories that ask | Everything else |
|---|---|---|
| `allow-everything` | (none — zero prompts) | allow |
| `allow-most` | `shell`, `shell_destructive` | allow |
| `allow-cautious` | `shell`, `shell_destructive`, `network` | allow |
| `ask` | every category | (n/a) |

## Safety reminders

- `allow-everything` is true zero-prompt mode. There is no safety net — `sudo`, `rm -rf /`, force-push, pipe-to-shell all auto-run. Only use on throwaway VMs or containers you can rebuild from scratch.
- `allow-most` is a sane middle ground for most users: every Bash command prompts (so you see what Claude wants to run), but file edits, web fetches, and git operations auto-allow.
- A malicious tool-result or web page could try to inject instructions Claude executes. If you've moved off `allow-everything`, the `ask` prompts are your line of defense — read each one before approving.