permissions-audit

name	permissions-audit
description	Use when reviewing, auditing, or cleaning up Claude Code permission allow, deny, and ask lists across settings files. Flags overly permissive patterns, deprecated syntax, duplicates, missing safety rules, and suggests project-type-aware additions.
user-invokable	true
args	[{"name":"command","description":"Scope ('global'/'project'/'all') or 'discover <tool-name>' to explore a CLI tool's commands","required":false}]

Audit Claude Code permission allow/deny/ask lists across all settings files. Classify issues by risk, suggest tightening, and interactively apply fixes. Can also discover permissions for new CLI tools.

Mode Selection

Parse the first argument to determine the mode:

• global, project, all, or no argument → Audit mode (Phases 1-4 below)
• discover <tool-name> → Discover mode (see Discover Mode section at the end)

Permission Model Reference

Claude Code has three permission arrays, evaluated in order: deny → ask → allow. First match wins.

Array	Behavior
allow	Auto-approved — no prompt
ask	Always prompts for confirmation
deny	Auto-rejected — tool cannot be used at all

Anything not matching any array falls through to the defaultMode setting. Use the right array for the intent:

• allow — safe, read-only, or frequently-used commands (linters, test runners, git log)
• ask — commands that should succeed but need human review each time (git commit, git push, deployments)
• deny — commands that should never execute, even if explicitly requested (force push, rm -rf /)

Phase 1: Discovery

Read all three settings files and detect the project type.

Settings Files

Read each file. If a file doesn't exist, note it and continue.

1. Global: ~/.claude/settings.json
2. Project shared: .claude/settings.json (in project root)
3. Project local: .claude/settings.local.json (in project root)

Extract permissions.allow, permissions.deny, and permissions.ask arrays from each. Also note the permissions.defaultMode value if set — it affects the overall security posture (see below). Ignore all other fields (env, hooks, model, statusLine, spinnerVerbs, etc.) — they are out of scope and must never be modified.

Default Mode Check

Read permissions.defaultMode from each file. Surface the value in the Phase 4 summary. Flag if set to a permissive mode:

Mode	Risk	Note
"default" or absent	OK	Standard behavior — prompts on first use
"plan"	OK	Requires plan approval
"dontAsk"	OK	Auto-denies unless pre-approved in allow rules
"bypassPermissions"	CRITICAL	All permission rules are ignored — every tool auto-approved
"acceptEdits"	HIGH	File edits auto-approved without review

Do not modify defaultMode — only surface it as informational context.

Project Type Detection

Check for indicator files in the project root to determine project type(s). A project can have multiple types.

Indicator	Type
pyproject.toml + uv.lock	Python/uv
pyproject.toml + poetry.lock	Python/Poetry
pyproject.toml (no uv.lock or poetry.lock)	Python (generic)
requirements.txt or setup.py (no pyproject.toml)	Python (pip)
package.json + package-lock.json	Node/npm
package.json + yarn.lock	Node/yarn
package.json + pnpm-lock.yaml	Node/pnpm
package.json + bun.lock or bun.lockb	Node/bun
Cargo.toml	Rust
go.mod	Go
pom.xml	Java/Maven
build.gradle or build.gradle.kts	Java/Gradle
*.csproj or *.sln	C#/.NET
Gemfile	Ruby
composer.json	PHP
*.tf files	Terraform
mise.toml or .mise.toml	Mise
docker-compose.yml or docker-compose.yaml or compose.yml	Docker
.github/ directory	GitHub
Makefile	Make

If mise is detected, run mise tasks ls to enumerate available task names. These feed into Phase 3 suggestions.

Scope Filtering

If the argument is one of the audit scopes:

• global — only audit ~/.claude/settings.json
• project — only audit .claude/settings.json and .claude/settings.local.json
• all (default) — audit all three files

No Project Directory

If run outside a project (no .claude/ directory in the working directory), gracefully skip project settings files and only audit the global settings. Note this in the Phase 4 summary. Project-type detection and project-type-aware suggestions are also skipped in this case.

Phase 2: Audit

Analyze every entry in every allow/deny/ask list. Classify each finding by risk level.

Risk Levels

Risk	Criteria	Examples
CRITICAL	Allows arbitrary execution or data destruction (in allow/ask)	Bash(*), Bash(sudo *), Bash(rm -rf *), credentials in patterns
HIGH	Broad wildcard on risky command family (in allow/ask)	Bash(docker compose *), Bash(find *), Bash(git *)
MEDIUM	Deprecated syntax, broader than necessary, duplicates, built-in overlap	:* patterns, redundant entries, Bash(grep *)
LOW	Hygiene/informational	Stale WebFetch domains, subset duplicates, style inconsistencies

Note: Broad patterns in deny are safety features, not risks — see check 1 for array-context-aware classification.

Checks to Perform

Run every check below against every entry. One entry can trigger multiple findings. When multiple checks flag the same entry, consolidate into a single finding using the highest severity and combining the rationale (e.g., an entry that is both overly permissive and in the wrong array → one finding, not two).

1. Overly Permissive Patterns

Flag entries in allow or ask that grant broad access to command families with known destructive subcommands. Skip this check for deny entries — broad patterns in deny are safety features, not risks.

Pattern	Risk (in allow)	Risk (in ask)	Why
Bash(*)	CRITICAL	HIGH	Allows any command
Bash(sudo *)	CRITICAL	HIGH	Root access
Bash(rm -rf *)	CRITICAL	HIGH	Arbitrary deletion
Bash(docker compose *) or Bash(docker compose:*)	HIGH	MEDIUM	Includes down -v, rm, exec
Bash(find *) or Bash(find:*)	HIGH	MEDIUM	-exec allows arbitrary execution
Bash(git *) or Bash(git:*)	HIGH	MEDIUM	Includes destructive ops (reset, clean, push --force)
Bash(npm *) or Bash(npm:*)	HIGH	MEDIUM	npm exec allows arbitrary execution
Bash(PGPASSWORD=* psql *) or Bash(PGPASSWORD=* psql:*)	CRITICAL	CRITICAL	Arbitrary SQL execution. If password is a literal (not *), also a credential exposure issue (see check 4)
Bash(terraform *) or Bash(terraform:*)	HIGH	MEDIUM	terraform apply, terraform destroy can modify/delete infrastructure
Bash(kubectl *) or Bash(kubectl:*)	HIGH	MEDIUM	kubectl delete, kubectl exec can destroy resources or run arbitrary commands
Bash(make *) or Bash(make:*)	HIGH	MEDIUM	Make targets are arbitrary shell commands — equivalent to Bash(*) for that target
Bash(yarn *) or Bash(yarn:*)	HIGH	MEDIUM	yarn dlx allows arbitrary execution; yarn run can execute any package.json script
Bash(pnpm *) or Bash(pnpm:*)	HIGH	MEDIUM	pnpm dlx/pnpm exec allows arbitrary execution; same risk profile as npm/yarn

Risk is lower in ask (user still confirms each use) but broad ask patterns still warrant tightening.

2. Deprecated Syntax

The legacy :* suffix syntax is deprecated. The current syntax uses a space: *.

• Bash(cmd:*) should be Bash(cmd *)
• Word boundary semantics: Bash(ls *) matches ls -la but NOT lsof. Bash(ls*) matches both.
• Flag ALL :* entries as MEDIUM risk

Caution — commands with literal colons: Many tools use colons in their command names: mise tasks (mise run fe:lint), Maven goals (mvn dependency:tree), npm scripts (npm run build:prod), Laravel artisan (php artisan migrate:fresh), Rake tasks (rake db:migrate), Gradle subprojects (gradle :app:build). A pattern like Bash(npm run build:*) looks like it should match npm run build:prod, but Claude Code interprets the trailing :* as the deprecated wildcard suffix — making it equivalent to Bash(npm run build *), which requires a space after "build" and will NOT match npm run build:prod. When flagging :* entries, check whether the colon is part of the actual command name. If it is, the entry may need to be rewritten as individual exact-match rules (e.g., Bash(npm run build:prod), Bash(npm run build:dev)) rather than simply migrated to *.

3. Duplicates

• Exact duplicates: Same string appears multiple times in the same file's allow, deny, or ask list
• Cross-file duplicates (same tier): Same rule in the same array type across global and project settings (e.g., both have Bash(uv sync) in allow). The project rule is redundant. Always flag — let the user decide whether to keep or remove
• Cross-file narrowing (different tier): A global allow + project ask for the same pattern is intentional narrowing — the project wants a prompt despite global auto-approve. Do NOT flag these as duplicates. Similarly, a project deny overriding a global allow is intentional restriction
• Subset duplicates: Bash(mise run check *) is a subset of Bash(mise run check:*) or vice versa. Bash(pip index *) subsumes Bash(pip index versions *)

4. Credential Exposure

Flag entries containing literal passwords, tokens, or secrets in patterns:

• PGPASSWORD=<literal>, MYSQL_PWD=<literal> — database password visible in config
• TOKEN=, SECRET=, API_KEY= in patterns
• DATABASE_URL= containing embedded credentials (e.g., postgres://user:pass@host/db)
• Risk: CRITICAL (credentials in plain text)

5. Built-in Tool Overlap

Claude Code has built-in tools that replace common shell commands. These Bash allows cause approval fatigue for no benefit:

Bash Pattern	Built-in Alternative	Note
Bash(grep *) or Bash(grep:*)	Grep tool	Remove — Grep tool is always available
Bash(find *) or Bash(find:*)	Glob tool	Remove or heavily scope — Glob handles file finding
Bash(cat *) or Bash(cat:*)	Read tool	Remove — Read tool handles file reading
Bash(head *), Bash(tail *)	Read tool (with offset/limit)	Remove
Bash(wc *) or Bash(wc:*)	Grep (count mode) or Bash	Low priority, but note overlap
Bash(tree *) or Bash(tree:*)	Glob + Bash(ls)	Low priority

6. Missing Deny/Ask Rules

Check if these baseline safety rules exist. If not, suggest adding them.

Suggested deny rules (should never execute):

• Bash(git push --force *) (or --force-with-lease, -f)
• Bash(git reset --hard *)
• Bash(git clean -f *)
• Bash(sudo *)
• Bash(rm -rf /*) (no space — matches rm -rf /etc, rm -rf /home, etc.)
• Bash(rm -rf ~*) (no space — matches rm -rf ~/Documents, rm -rf ~, etc.)

Suggested ask rules (should prompt, not auto-approve or auto-deny):

• Bash(git commit *) — human should review before committing
• Bash(git push *) — human should review before pushing (deny rules for --force take precedence, so this is safe)

Check all three arrays across global and project settings. Global is preferred for baseline safety rules.

7. Wrong Array Placement

Flag entries in the wrong permission array:

• Destructive commands in allow that should be in deny or ask (e.g., Bash(git push --force *) in allow)
• Review-worthy commands in allow that should be in ask (e.g., Bash(git commit *) in allow — human should review)
• Safe read-only commands in deny or ask that could be in allow (e.g., Bash(git log *) in ask)
• Commands in deny that block legitimate use — suggest ask instead if the command is sometimes needed (e.g., Bash(git commit *) in deny blocks all commits; ask allows with confirmation)

8. Misplaced Rules

Flag project-specific entries in global settings that should live in the relevant project's .claude/settings.json or .claude/settings.local.json:

• Project-specific test runners (e.g., Bash(npx vitest run *), Bash(npx jest *), Bash(npx cypress run *))
• Project-specific tool setup (e.g., Bash(npx playwright install *))
• Database access with credentials (e.g., Bash(PGPASSWORD=postgres psql *), Bash(MYSQL_PWD=root mysql *))
• Project-specific WebFetch domains that only apply to one project
• Entries referencing project-specific commands not used across projects

Heuristic: If a command is only relevant to one project type (e.g., a specific test runner, a specific database), it likely belongs in project settings. Misplaced rules are MEDIUM severity (global pollution) or LOW if debatable.

9. Syntax Inconsistencies

Flag when the same logical command uses different pattern styles across files:

• Same command with :* in one file and * in another
• Same command with wildcard in one file and exact match in another (e.g., Bash(uv sync) in project vs Bash(uv sync:*) in global)

10. Broad Non-Bash Tool Patterns

Not all permissions are Bash commands. Flag overly broad patterns for other tool types:

Pattern	Risk	Why
mcp__* or mcp__<server>__* in allow	HIGH	Grants all operations for an MCP server — some may be destructive
Read(*) or Write(*) in allow	HIGH	Unrestricted file read/write, including secrets
Edit(*) in allow	MEDIUM	Unrestricted file editing
WebFetch(*) in allow	LOW	Informational — broad but low-risk
WebSearch in allow	LOW	Informational — WebSearch has no (*) pattern (it's a bare tool name), but auto-approving it is low-risk

For MCP wildcards like mcp__logfire__*, suggest scoping to specific operations if the server's available tools are known. Otherwise flag as HIGH and note that the risk depends on what the server exposes.

11. Usage Log Analysis (optional)

If ~/.claude/tool-usage.log exists (created by the companion logging hook — see Usage Logging section), analyze it for:

• Frequently used Bash commands not in any allow list → suggest adding to reduce approval fatigue
• Commands that appear in allow but were never used in the log period → flag as potentially stale (LOW)

This check is informational only — findings are LOW severity and presented as suggestions in Phase 3 Step 3 (batch additions). If the log file doesn't exist, skip this check silently.

Settings File Merge Semantics

Permission arrays (allow, deny, ask) are concatenated across all settings files — not replaced. Then rules are evaluated in order: deny → ask → allow, first match wins. This means if a pattern appears in deny in ANY file, it's denied — no other file can override it. Same for ask over allow.

Examples:

• Global allow + project deny for same pattern → denied (deny checked first)
• Global allow + project ask for same pattern → prompted (ask checked before allow)
• Global ask + project allow for same pattern → prompted (ask checked before allow)
• Global deny + project allow for same pattern → denied (deny checked first)

Scalar settings like defaultMode are replaced by higher-precedence scopes (local > shared > global), not merged.

Cross-file "narrowing" (a project adding an ask or deny for something globally allowed) is a legitimate pattern, not a conflict. Use this understanding when assessing cross-file duplicates (check 3) and misplaced rules (check 8).

Phase 3: Suggest

Generate two categories of recommendations.

A. Tighten Existing Rules

For entries flagged HIGH or CRITICAL, suggest specific replacements:

Current	Suggested Replacements
Bash(docker compose *)	Bash(docker compose up *), Bash(docker compose ps *), Bash(docker compose logs *), Bash(docker compose build *) (omit exec — runs arbitrary commands in containers)
Bash(docker compose:*)	Same as above (also migrates deprecated syntax)
Bash(find *)	Remove (use Glob) or scope: Bash(find * -name *), Bash(find * -type *)
Bash(find:*)	Same as above
Bash(git *)	allow: Bash(git status *), Bash(git log *), Bash(git diff *), Bash(git branch *), Bash(git show *), Bash(git stash list *), Bash(git stash show *), Bash(git stash push *); ask: Bash(git commit *), Bash(git push *), Bash(git stash drop *) (data loss)
Bash(git:*)	Same as above
Bash(PGPASSWORD=<literal> psql *)	Remove from global. If needed in a project, add to that project's .claude/settings.local.json with tighter scope
Bash(npm *)	Bash(npm test *), Bash(npm run lint *), Bash(npm run build *), Bash(npm install *), Bash(npm ls *) (avoid blanket npm run * — can execute any package.json script including deploys/migrations)
Bash(terraform *)	allow: Bash(terraform init *), Bash(terraform plan *), Bash(terraform fmt *), Bash(terraform validate *); ask: Bash(terraform apply *), Bash(terraform import *); deny: Bash(terraform destroy *)
Bash(kubectl *)	allow: Bash(kubectl get *), Bash(kubectl describe *), Bash(kubectl logs *); ask: Bash(kubectl apply *), Bash(kubectl create *), Bash(kubectl exec *); deny: Bash(kubectl delete *)
Bash(make *)	Remove and enumerate individual safe targets from Makefile as exact matches (e.g., Bash(make test), Bash(make lint)). Do NOT suggest Bash(make *) — make targets can run arbitrary commands
Bash(yarn *)	Bash(yarn test *), Bash(yarn lint *), Bash(yarn build *), Bash(yarn tsc *) (avoid blanket yarn run * — same risk as npm run *)
Bash(pnpm *)	Bash(pnpm test *), Bash(pnpm run lint *), Bash(pnpm run build *), Bash(pnpm exec tsc *) (avoid blanket pnpm run *)

B. Add Missing Rules (Project-Type-Aware)

Based on detected project type, suggest additions unless the rule already exists in any settings file. Target the appropriate file:

• .claude/settings.json (project shared) — team-visible rules: test runners, linters, build commands, dev servers
• .claude/settings.local.json (project local) — personal/credential-adjacent rules: database access with passwords, local tool configs, user-specific commands. Note: This file should be in .gitignore to avoid committing credentials to version control.

Project Type	Suggested Allows
Python/uv	Bash(uv sync), Bash(uv run pytest *), Bash(uv pip show *), Bash(uv pip index versions *), Bash(uv lock)
Python/Poetry	Bash(poetry install), Bash(poetry run pytest *), Bash(poetry lock), Bash(poetry show *)
Python (pip)	Bash(pip install *), Bash(pip show *), Bash(python -m pytest *), Bash(pip freeze)
Node/npm	Bash(npm test *), Bash(npm run lint *), Bash(npm run build *), Bash(npx tsc *)
Node/yarn	Bash(yarn test *), Bash(yarn lint *), Bash(yarn build *), Bash(yarn tsc *)
Node/pnpm	Bash(pnpm test *), Bash(pnpm run lint *), Bash(pnpm run build *), Bash(pnpm exec tsc *)
Node/bun	Bash(bun test *), Bash(bun run lint *), Bash(bun run build *) (avoid blanket bun run * — same risk as npm run *)
Rust	Bash(cargo build *), Bash(cargo test *), Bash(cargo clippy *), Bash(cargo fmt *)
Go	Bash(go build *), Bash(go test *), Bash(go vet *)
Java/Maven	Bash(mvn compile *), Bash(mvn test *), Bash(mvn package *), Bash(mvn dependency:tree *)
Java/Gradle	Bash(./gradlew build *), Bash(./gradlew test *), Bash(./gradlew check *)
C#/.NET	Bash(dotnet build *), Bash(dotnet test *), Bash(dotnet run *), Bash(dotnet restore *)
Ruby	Bash(bundle exec rspec *), Bash(bundle exec rake *), Bash(bundle exec rubocop *), Bash(bundle install)
PHP	Bash(composer install), Bash(./vendor/bin/phpunit *), Bash(./vendor/bin/phpstan *). For Laravel: allow Bash(php artisan list *), Bash(php artisan route:list *), Bash(php artisan tinker *); ask Bash(php artisan migrate *), Bash(php artisan db:seed *); deny Bash(php artisan migrate:fresh *), Bash(php artisan db:wipe *)
Terraform	allow: Bash(terraform init *), Bash(terraform plan *), Bash(terraform fmt *), Bash(terraform validate *); ask: Bash(terraform apply *), Bash(terraform import *); deny: Bash(terraform destroy *)
Mise	One Bash(mise run <task>) or Bash(mise run <task> *) for each task from mise tasks ls. If a task is read-only (test, lint, typecheck, check), use exact match. If a task takes arguments, use wildcard.
Docker	allow: Bash(docker compose up -d), Bash(docker compose ps *), Bash(docker compose logs *), Bash(docker compose build *); ask: Bash(docker compose down *)
GitHub	Bash(gh pr list *), Bash(gh pr view *), Bash(gh pr diff *), Bash(gh issue list *), Bash(gh issue view *)
Make	Individual Bash(make <target>) entries for each safe target (read the Makefile to enumerate). Do not suggest Bash(make *) — make targets can run arbitrary commands

Also suggest baseline deny and ask rules if missing (see Phase 2, check 6).

Do NOT suggest rules that already exist in any of the three settings files, even if in a different syntax variant. Check for semantic equivalence: Bash(uv sync) ≈ Bash(uv sync *) ≈ Bash(uv sync:*).

Phase 4: Interactive Apply

Present findings and apply changes interactively. NEVER auto-modify settings files without explicit user approval for each change.

CRITICAL INTERACTION RULE: This phase is iterative. Present ONE step at a time, pause for user input using AskUserQuestion, apply changes, then continue to the next step. NEVER output multiple steps in a single response. Each response should contain at most ONE issue or ONE batch group.

Step 0: Backup

Before making any changes, create backups of settings files that have no automatic git backup:

• ~/.claude/settings.json → ~/.claude/settings.backup.json
• .claude/settings.local.json → .claude/settings.local.backup.json (if it exists)

.claude/settings.json (project shared) is tracked by git — no backup needed (git checkout can restore it).

Use the Bash tool to copy: cp ~/.claude/settings.json ~/.claude/settings.backup.json. If a backup already exists from a previous run, overwrite it (only the most recent backup is kept). Inform the user which backups were created.

Step 1: Summary

Present only the summary table, then immediately use AskUserQuestion to ask the user if they want to proceed with the issue-by-issue review.

## Permissions Audit Results

**Project type**: Python/uv + Mise + Docker + GitHub
**Files scanned**: 3 (global, project shared, project local)
**Default mode**: plan (OK)

| Severity | Count |
|----------|-------|
| CRITICAL | N     |
| HIGH     | N     |
| MEDIUM   | N     |
| LOW      | N     |

**N tightening recommendations, N additions suggested**

Then use AskUserQuestion with the question: "Ready to review issues? (yes / skip to additions / skip to syntax migration / done)"

Step 2: Issue-by-Issue Review

Present issues one at a time in severity order: CRITICAL first, then HIGH, MEDIUM, LOW.

For each issue:

1. Output the issue description (ONE issue only)
2. Use AskUserQuestion to ask: "Accept / Reject / Skip?" (include issue number and total, e.g. "Issue 1/11")
3. Wait for the response
4. If accepted, apply the change using Edit tool, then confirm it was applied
5. Present the NEXT issue and repeat

Issue format:

### [SEVERITY] Issue Title (N of M)
**File**: ~/.claude/settings.json (global)
**Current**: `Bash(docker compose:*)`
**Problem**: Broad wildcard on command family with destructive subcommands (down -v, rm). Also uses deprecated `:*` syntax.
**Proposed**:
  - Remove: `Bash(docker compose:*)`
  - Add: `Bash(docker compose up *)`, `Bash(docker compose ps *)`, `Bash(docker compose logs *)`, `Bash(docker compose build *)`

When an entry is being modified for any reason (tightening, dedup, relocation), also migrate :* to * in the same edit. Do NOT create separate issues for :* migration on entries already being modified.

If the user says "accept all" or "accept remaining", apply all remaining issues without further prompting and report what was done.

Step 3: Batch Additions

After all individual issues are resolved, present project-type suggestions as a single group, then use AskUserQuestion to ask: "Add all / Pick individually / Skip all?"

### Suggested Additions for Python/uv + Mise project

These commands are commonly needed but not in your allow/ask lists:

| # | Rule | Array | File | Rationale |
|---|------|-------|------|-----------|
| 1 | `Bash(mise run dev)` | allow | project shared | Dev server task |
| 2 | `Bash(gh issue list *)` | allow | global | GitHub issue browsing |
| 3 | `Bash(git push *)` | ask | global | Push with human review |
| ... | ... | ... | ... | ... |

If "pick individually", present each addition one at a time using AskUserQuestion for each.

Step 4: Remaining Deprecated Syntax

After all other changes, if there are :* entries that were NOT touched in Steps 2-3, present the migration table and use AskUserQuestion to ask: "Migrate all / Pick individually / Skip?"

Before presenting the table, check each entry for literal colons — see the caution note in Check 2. If the colon appears to be part of the command name (e.g., Bash(mise run fe:lint:*), Bash(npm run build:*)), flag it separately and suggest rewriting as exact-match rules instead of blindly migrating :* → *.

### Deprecated `:*` Syntax Migration

N entries still use the deprecated `:*` syntax:

| Current | Migrated |
|---------|----------|
| `Bash(tree:*)` | `Bash(tree *)` |
| `Bash(ls:*)` | `Bash(ls *)` |
| ... | ... |

Step 5: Final Summary

After all changes are applied, present a single summary:

## Audit Complete

**Applied**: N changes across M files
**Skipped**: N items
**Rejected**: N items

Changes made:
- [file]: removed N entries, added N entries, migrated N syntax
- [file]: ...

JSON Editing Rules

Settings files are JSON. Follow these rules strictly:

1. Read before edit: Always Read the file immediately before editing to get current content
2. Targeted array edits: Use the Edit tool to modify specific entries in the permissions.allow, permissions.deny, or permissions.ask arrays. Never rewrite the entire file.
3. Preserve structure: Never modify, reorder, or touch any fields outside of permissions.allow, permissions.deny, and permissions.ask
4. Validate after every edit: After each edit, validate the file is still valid JSON:
   1. Output a message first: Tell the user what you're about to do (e.g., output "Validating JSON…") so they understand the upcoming Bash command.
   2. Run validation: python3 -c "import json; json.load(open('<file_path>'))".
   3. If validation fails, immediately fix the issue before proceeding. This is mandatory — a broken settings file will prevent Claude Code from starting.
5. Array operations:
   • Remove entry: Edit the array to remove the specific line. CRITICAL: When removing the last entry in an array, also remove the trailing comma from the new last entry. JSON does not allow trailing commas. Example: removing entry C from ["A", "B", "C"] must produce ["A", "B"], not ["A", "B",].
   • Add entry: Edit to insert at the end of the array before the closing ]. Add a comma after the current last entry.
   • Replace entry: Edit old string to new string
   • Create array: If the file has no ask (or deny) array and one is needed, add it as a sibling to the existing arrays inside the permissions object. Example: insert "ask": ["Bash(git commit *)"] after the allow array's closing ]
6. Batch edits: When multiple changes apply to the same file, make them in a single Edit operation to avoid intermediate invalid states
7. Backup note: Step 0 creates backups before changes. Project shared settings can also be restored with git checkout. Remind the user that ~/.claude/settings.backup.json exists if they need to revert.

NEVER Rules

• NEVER modify settings without explicit user approval for each change
• NEVER touch non-permission fields (env, hooks, model, statusLine, spinnerVerbs, enabledPlugins, etc.)
• NEVER remove deny or ask rules without explicit user request — these are safety boundaries
• NEVER add overly broad patterns as suggestions (no Bash(git *), always scoped)
• NEVER guess at project-specific commands — only suggest what's detected from indicator files and tool output
• NEVER migrate :* syntax on entries that aren't being touched for another fix (unless user opts into batch migration in Step 4)
• NEVER assume WebFetch domains are stale — only flag if user confirms the domain is no longer needed
• NEVER rewrite entire settings files — always use targeted edits

Discover Mode

When invoked with /permissions-audit discover <tool-name>, explore a CLI tool and suggest permission entries without running a full audit.

Step 1: Explore the tool

1. Run <tool> --help (or <tool> -h, <tool> help) to get top-level commands/subcommands
2. For command groups that have their own subcommands, recurse one level: <tool> <group> --help
3. Stop at 2 levels of depth to avoid excessive exploration
4. If the tool is well-known (kubectl, aws, gcloud, az, gh, docker, terraform, helm), leverage knowledge of its command tree to supplement --help output

Security: Only run --help / -h / help subcommands. Never run the tool's actual commands (e.g., don't run kubectl delete namespace prod to "test" it). Discovery is read-only.

Step 2: Determine target file

Before suggesting entries, ask the user where rules should go. Use AskUserQuestion:

• Global (~/.claude/settings.json) — if the tool is used across projects
• Project shared (.claude/settings.json) — if team-shared for this project
• Project local (.claude/settings.local.json) — if personal/credential-adjacent

Step 3: Read existing settings

Read the target file (and all other settings files) to collect existing permission entries. This is needed to avoid suggesting entries that already exist — check for semantic equivalence: Bash(cmd) ≈ Bash(cmd *) ≈ Bash(cmd:*).

Step 4: Categorize and suggest

Classify each discovered command by risk:

Category	Keyword signals	Target array
Read-only	list, get, show, describe, search, status, version, info, view, inspect, logs, whoami	allow
Write (reversible)	create, update, set, configure, run, start, stop, restart, trigger, push, apply	ask
Write (destructive)	delete, destroy, remove, purge, drop, force, reset, wipe, terminate	deny

Filter out any entries that already exist in any settings file. Present remaining suggestions using the same interactive format as Phase 4 Step 3 (batch additions with AskUserQuestion).

Format: Bash(<tool> <subcommand> *) scoped to specific subcommands — never suggest Bash(<tool> *).

Step 5: Backup and apply

Before writing any changes, create a backup of the target file (same as Phase 4 Step 0 — cp <file> <file>.backup). Then apply accepted entries using the JSON Editing Rules.

Usage Logging (Optional)

An optional companion hook that logs Bash tool usage to ~/.claude/tool-usage.log. This enables check 11 (usage log analysis) in audit mode. The audit skill works fully without this hook — it only adds usage-pattern suggestions.

Tradeoffs

Before installing, understand what you're opting into:

Benefit	Cost
Identifies frequently-prompted commands to add to allow	Adds ~5-10ms overhead per Bash tool call (fork + jq + sed + file write)
Surfaces stale allow entries you never use	Logs every Bash command to disk in plaintext
Reduces approval fatigue over time	Redaction is best-effort — secrets in non-KEY=VALUE formats can leak (e.g., curl -H "Authorization: Bearer sk-...", base64 tokens as positional args)

Recommendation: Install it, let it collect data for a week or two, run /permissions-audit to get suggestions, then uninstall it. Don't leave it running permanently.

Installation

Requires jq (JSON processor). The script silently does nothing if jq is not available.

1. Copy: cp hooks/log-tool-usage.sh ~/.claude/hooks/
2. Chmod: chmod +x ~/.claude/hooks/log-tool-usage.sh
3. Add a PostToolUse entry inside your existing hooks object in ~/.claude/settings.json:

"PostToolUse": [
  {
    "matcher": "Bash",
    "hooks": [
      {
        "type": "command",
        "command": "~/.claude/hooks/log-tool-usage.sh"
      }
    ]
  }
]

Important: If you already have a hooks object (e.g., with PreToolUse), add PostToolUse as a sibling key — don't replace the entire hooks object.

Uninstallation

Remove the PostToolUse entry from ~/.claude/settings.json and optionally delete the log:

rm ~/.claude/hooks/log-tool-usage.sh
rm ~/.claude/tool-usage.log

What it logs

Each line: <ISO-8601 timestamp> <redacted command>

Secrets are redacted before writing: KEY=VALUE patterns where KEY contains PASSWORD, TOKEN, SECRET, API_KEY, CREDENTIAL, AWS_SECRET_ACCESS_KEY, PRIVATE_KEY, DATABASE_URL, REDIS_URL, MONGO_URI, DSN, or MYSQL_PWD have their value replaced with ***REDACTED***. Both unquoted (KEY=value) and quoted (KEY="value", KEY='value') forms are redacted.

Redaction is best-effort. It does NOT catch: secrets as positional arguments, bearer tokens in headers, base64-encoded credentials, or any format that isn't KEY=VALUE. The log file is written with 0600 permissions (owner-only read/write).

What it does NOT log

• Tool output (only the command string, not stdout/stderr)
• Non-Bash tool calls (Read, Write, Edit, etc.)
• Commands that were denied (PostToolUse only fires after successful execution)
• Commands that failed (PostToolUseFailure is a separate event, not hooked)

Known limitations

• PreToolUse hook rewrites: If you have PreToolUse hooks that rewrite commands (e.g., rtk token optimizer), the log captures the rewritten command, not the original. Permission rules match against the original command, so audit suggestions based on the log may not match the actual permission patterns needed. The audit accounts for this by treating log-based suggestions as informational (LOW severity).
• Multiline commands: Commands with heredocs or &&-chains are collapsed to a single line (newlines replaced with spaces) to preserve the one-entry-per-line log format.

Safety: exit code handling

PostToolUse hooks that exit non-zero can block Claude Code from executing further commands (github.com/anthropics/claude-code/issues/4809). The hook script uses trap 'exit 0' ERR to guarantee it always exits cleanly, even if jq, sed, or file I/O fails.

Log management

The log file grows unbounded. Periodically check its size and truncate:

wc -c ~/.claude/tool-usage.log   # check size
# Stop the hook (remove PostToolUse entry) before truncating to avoid data loss from concurrent writes
tail -1000 ~/.claude/tool-usage.log > ~/.claude/tool-usage.log.tmp && mv ~/.claude/tool-usage.log.tmp ~/.claude/tool-usage.log  # keep last 1000 entries

The audit skill only reads the log — it never modifies or deletes it.