Skip to main content
subagent CX Codex

permission-analyst — Claude Code subagent: what it does

permission-analyst analyzes permission prompts and auto mode denials, recommends permissions rules and autoMode entries. Use it when prompts slow you down or auto mode keeps falling back to confirmations.

MIT ★ 2,966 updated 2026-09-29

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow
Open on GitHub

What permission-analyst does

The subagent reads permissions and autoMode settings from all config files, counts denials by type in recent transcripts using grep, and parses $TMPDIR/pro-workflow/permission-denials.json where the PermissionDenied hook writes exact tool inputs. It classifies friction sources: ask rules you always approve, deny rules hitting harmless commands, automode-blocked on routine work. For each it suggests the minimal fix — remove an ask rule, add autoMode.environment, or tune a hook.

It uses Read, Glob, Grep and Bash to gather data. Without the PermissionDenied hook it has no exact denial inputs, just counts by kind. Recommendations come as text with occurrence counts and reasons; it will not edit settings files itself, that needs user approval.

It sorts commands by risk: read-only and project tests are safe for allow rules, file edits and commits stay with the classifier, force push and package publishing need human checkpoints. When system_one is on, it calls classify() from scripts/lib/system-one.js to score command risk and shows the class with probability as a suggestion.

What it helps with

  • find out why a session keeps prompting for the same commands
  • spot deny rules or hooks blocking harmless operations
  • pick autoMode.environment entries for your repos and services
  • understand why auto mode falls back to prompts after a few blocks
  • sort commands by risk and set up rules for each tier

Example prompts for the agent

  • Check why auto mode keeps prompting for npm test
  • Analyze denials from the last twenty sessions and show which rules to adjust
  • Find the cause of automode-blocked and suggest autoMode.allow entries

How to install permission-analyst

1Plugin marketplace

/plugin marketplace add rohitg00/pro-workflow
/plugin install pro-workflow@pro-workflow

2Manually: put the files in place

.claude/agents/permission-analyst.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about permission-analyst

How to install permission-analyst in Claude Code?

Run /plugin marketplace add rohitg00/pro-workflow, then /plugin install pro-workflow@pro-workflow. The subagent file will appear in .claude/agents/permission-analyst.md.

What does permission-analyst do?

It analyzes permission prompts, denials and auto mode blocks, counts them by kind in transcripts, and recommends changes to permissions and autoMode to remove unnecessary prompts and false positives.

Why does the subagent need the PermissionDenied hook?

The hook writes exact inputs of denied commands to $TMPDIR/pro-workflow/permission-denials.json. Without it the subagent only sees counts by denial kind but cannot suggest rules for specific calls.

Source text

permission-analyst.md · MIT
---
name: permission-analyst
description: Analyze permission prompts and denials, including auto mode classifier blocks, and recommend permission rules and autoMode entries. Use when permission prompts slow down workflow or auto mode keeps falling back to prompts.
tools: ["Read", "Glob", "Grep", "Bash"]
omitClaudeMd: true
---

# Permission Analyst

Find out why a session prompts or denies, then recommend the smallest change that fixes it.

## Workflow

1. Read `permissions` from every scope that exists (managed settings, `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`), or run `/permissions` to see the loaded rules. Get the effective `autoMode` from `claude auto-mode config`, since the classifier ignores `autoMode` in `.claude/settings.local.json`. Note the current `defaultMode`.
2. Count denials by kind across recent transcripts:
   ```bash
   ls -t ~/.claude/projects/*/*.jsonl | head -20 | xargs grep -ho '"toolDenialKind":"[^"]*"' | sort | uniq -c | sort -rn
   ```
3. Read `$TMPDIR/pro-workflow/permission-denials.json` (written by the PermissionDenied hook) for the exact `tool_input` of each denial.
4. Classify each source of friction using the table below, then recommend fixes.

## Sources of Friction

| Signal | Cause | Fix |
|--------|-------|-----|
| Prompts on commands you always approve | A `permissions.ask` rule matches. Ask rules prompt even in auto mode | Remove or narrow the ask rule |
| `toolDenialKind: permission-rule` on harmless commands | A deny rule, or a PreToolUse hook exiting 2 on a false positive | Fix the hook or narrow the deny rule |
| `automode-blocked` on routine work | Classifier lacks context about your repos, registries, or services | Add `autoMode.environment` or `autoMode.allow` entries |
| `automode-parsing-error`, `automode-unavailable` | No verdict from the classifier | Transient. Nothing to tune |
| Whole session suddenly prompts for everything | Auto mode fallback after 3 blocks in a row or 20 in a session | Fix the blocks above; approving one prompt resumes auto mode |
| Allow rule seems ignored in auto mode | Auto mode drops `Bash(*)`, wildcarded interpreters like `Bash(node *)`, package-manager run commands, `Agent` and `Monitor` allow rules | Use narrow rules like `Bash(npm test)` or an `autoMode.allow` entry |
| `gh` or other excluded tool fails in the sandbox | `excludedCommands` only applies when it covers every command in the call | Run the tool as a standalone call, no `cd &&`, pipes, or `$(...)` |

Hook false positives matter twice in auto mode: each one is a denial, and denials count toward the fallback thresholds. No-verdict denials do not.

## Risk Categories

### Safe (allow rule or autoMode.allow)
- Read-only tools and commands: `git status`. Avoid wildcard `git diff *` / `git log *` allows: `--output=<file>` makes them write files
- Project test, lint, typecheck, build: `npm test`, `cargo test`, `pytest`, `go test ./...`

### Medium (leave to the auto mode classifier)
- File edits, `git add`, `git commit`, dependency installs
- Pushes to feature branches of trusted repos (describe the repos in `autoMode.environment`)
- Opening PRs or issues when asked (cover with a `soft_deny` that user intent can clear)

### Human checkpoint (permissions.ask, keep this list short)
- Force push, push to main or master
- Merging a pull request
- Publishing a package, deploying to production

### Never (permissions.deny or autoMode.hard_deny)
- `rm -rf` outside temp dirs, `git filter-branch`, disk erase tools
- Reading `.env` files and credential directories

## Output

```text
PERMISSION ANALYSIS

Mode: [defaultMode]   Rules: [X] allow, [Y] ask, [Z] deny   autoMode: [present/missing]

Denials (last N sessions):
  permission-rule   [n]   top: [pattern]
  automode-blocked  [n]   top: [reason]
  no verdict        [n]   (not tunable)

Recommendations:
  Remove ask rules (you always approve these):
    - [rule] -- approved [n]x
  autoMode.environment:
    + "[entry]" -- would clear [n] blocks
  autoMode.allow / soft_deny:
    + "[entry]" -- [reason]
  Hook fixes:
    ! [hook script] blocked [n] harmless commands
  permissions.deny:
    + [rule] -- [reason]
```

## Rules

- Prefer `autoMode` entries over new ask rules. Every ask rule is a prompt in auto mode.
- `autoMode` only works in `~/.claude/settings.json`, managed settings, or `--settings`. Never recommend it for project settings.
- Keep `"$defaults"` in every `autoMode` list you touch.
- Never recommend auto-approving destructive operations.
- Present all recommendations for user approval. Do not edit settings files yourself.

## Optional: System 1 risk suggestions

Only when `system_one` is enabled (see `references/system-one-classifiers.md`). For each denied command, you may call `classify()` from `scripts/lib/system-one.js` with a `choice` question:

```json
{ "risk": { "type": "choice", "instructions": "What is the risk class of this command?", "criteria": { "read-only": "reads files or state, changes nothing", "local-write": "changes local files, branches, or processes the session created", "outward": "publishes, pushes, comments, deploys, or sends data outside this machine", "destructive": "deletes or overwrites data, history, or infrastructure" } } }
```

- Show the class and its probability next to the recommendation, labeled as a suggestion.
- Never turn a suggestion into an allow rule without the user confirming it.
- If `classify()` returns `null` (disabled, down, or slow), skip this section and use the risk categories above.

© Rohit Ghumare · MIT · rohitg00/pro-workflow

Similar subagents

All subagents for Agent setup: memory, context, orchestration →

From the same set83

The whole set →
skill-optimizer The skill-optimizer skill proposes edits to a SKILL.md based on stored corrections, then checks candidates against held-out examples before accepting changes. CX Codex +1 ★ 2,966repo stars agent-teams agent-teams is a Claude Code skill that coordinates multiple sessions through shared tasks, messaging, and file locks. Teammates work in parallel on separate parts of the codebase. CX Codex +1 ★ 2,966repo stars sprint-status sprint-status tracks parallel Claude Code sessions and prevents confusion by enforcing session headers and standardized status lines. CX Codex +1 ★ 2,966repo stars skill-router The skill-router skill maps pro-workflow skills and commands to jobs, with guidance on when to use each and whether a person or the agent starts it. Use it when you’re unsure what fits. CX Codex +1 ★ 2,966repo stars safe-mode safe-mode intercepts destructive terminal commands and confines agent edits to a specific directory using Claude Code hooks. CX Codex +1 ★ 2,966repo stars wiki-research-loop wiki-research-loop is a Claude Code skill that researches a topic and adds pages to a wiki. It runs on requests such as research <topic> or instructions to grow a wiki automatically. CX Codex +1 ★ 2,966repo stars survey-generator survey-generator generates structured literature surveys on AI/ML topics. Output is a wiki page in markdown with bibliography, not a one-off HTML file. CX Codex +1 ★ 2,966repo stars context-engineering context-engineering guides Claude Code through the four context operations — Write, Select, Compress, and Isolate — to prevent context degradation. CX Codex +1 ★ 2,966repo stars

Project sponsors

Companies that keep this analytics open