# Audit Permission Grants

> Audit Claude Code permission grants (allowed-tools frontmatter and permissions.allow in every settings scope) for portability and auto-mode durability: dropped interpreter wildcards, machine-specific paths, literal substitution tokens, inert plugin self-grants. Report-only. Use when: 'check permission rules', 'why was my allowed-tools grant ignored', 'audit allow rules', 'is this permission portable', or a guarded helper is denied despite an allow rule. Effective state: audit-permission-state.

- Skill: `melodic-software/audit-permission-grants-2` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx get-skill add melodic-software/audit-permission-grants-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/melodic-software/audit-permission-grants-2/raw
- Safety review: pending (external: skill-scanner PASS, skillspector WARNING)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: melodic-software (https://skillmd.com/u/melodic-software)
- Updated: 2026-11-12
- Page: https://skillmd.com/skills/melodic-software/audit-permission-grants-2

---


**Arguments.** `[frontmatter|settings|plugins|all] [--unattended]`. default: all

## Purpose

Audit whether a repo's permission **grants** actually take effect. Answers a question the sibling
`audit` skill does not: "Are our allow-rules and `allowed-tools` grants portable across
machines and durable when the session enters auto mode, and is the operative rule in a place that can
work?"

The principle, the three anti-patterns, and the correct pattern (with official-doc citations) live in
the marketplace's **permission-rule-hygiene** convention, published at
<https://raw.githubusercontent.com/melodic-software/claude-code-plugins/main/docs/contracts/permission-rule-hygiene/README.md>.
The mechanical check definitions (P1/P2/P3, severities, detector invocation) are in
[reference/criteria.md](reference/criteria.md), which carries every recommendation this skill needs at
run time. The convention is the doctrine's owner, not a runtime dependency.

## Scope boundary (route out)

This skill owns grant portability + auto-mode durability + who adds the operative rule. It does **not**
own config-file correctness. Baseline deny/ask presence, overly broad patterns, and live plugin
drift belong to the sibling `audit` skill. When a request is about
those, route it there rather than answering here. The `audit` skill in the `harness-memory` plugin
owns the instruction layer (CLAUDE.md / a natively read AGENTS.md / rules / auto-memory).

## Arguments

Parse `$ARGUMENTS` for an optional scope filter. **It narrows which checks may produce findings,
never what the detector scans.** One full detector run happens either way, and the filter is
applied to its output:

- `frontmatter`: skill/command/agent `allowed-tools` only
- `settings`: project, local, and user-global `permissions.allow` only
- `plugins`: plugin `settings.json` self-grant (P3) only
- `all`: everything (default)

`--unattended`, anywhere in the arguments, is not a filter: the caller declares nobody is present, which changes only
the `/permissions` offer (see "Boundary" below). Take it out before reading the filter, and never
pass it to the detector.

The filter reads like a scan-scope, but a detector-side scope flag would buy nothing: the root is a
git toplevel, `$CLAUDE_PROJECT_DIR`, or an explicitly named directory, never an unbounded sweep, and
the walk takes well under a second. A second place for scope to be defined would only add drift. The
coverage block still reports the whole denominator on a filtered run, so a narrowed report never
implies a narrowed scan.

This skill is report-only. There is no `--fix`: the correct P3 remediation is inherently
operator-manual (the bare-name rule must land in user-global `~/.claude/settings.json`, which a skill
or plugin cannot write), and P1/P2 rewrites are judgment calls the operator confirms.

## Phase 1: Detect

Run the deterministic spine:

```shell
bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-permission-grants/scripts/permission-rule-check.sh"
```

It scans frontmatter `allowed-tools` and settings `permissions.allow` across the consuming repo and
the user-global settings file (`${CLAUDE_CONFIG_DIR:-$HOME/.claude}/settings.json`), and prints one
finding per fragile grant (`<severity> [<check>] <source>: <detail>`). `--count` prints the count.
**Exit 2 is the environment-gap channel: report the gap rather than a clean bill.** It is raised by a
missing `jq` (its message names the platform's install command when it finds one), a missing
shared pattern library, a scan root that resolves to neither a git toplevel nor
`$CLAUDE_PROJECT_DIR`, and any argument the script does not recognize. An unresolvable **user**
scope is not one of them: the run records it in the coverage block, says so on stderr, and
continues.
On an unresolvable project root, say the scan did not run and
give the fix: run from inside the repository you mean to scan, or set
`$PERMISSION_HYGIENE_SCAN_ROOT` explicitly. That variable is a supported operator lever, not a
test-only seam; `$PERMISSION_HYGIENE_FIXTURE_DIR` still works as a back-compatible alias and the new
name wins when both are set. Never report "no fragile permission grants found" on an exit 2.
`settings.local.json` is parsed for its `permissions.allow` array only, never echoed wholesale.

### Report the denominator, always

Every run ends with a **coverage block**. It is what makes a clean result readable. Carry its
numbers into the report:

- **A clean bill needs a non-zero denominator.** `No fragile permission grants found.` is printed
  only when the run actually parsed at least one `allowed-tools` block or allow rule. When it parsed
  none the detector prints `NOTHING TO AUDIT` instead. **Relay that as the outcome; never soften it
  into a clean bill.** A scan of nothing is not evidence about grants.
- **A clean bill also needs every input to have been readable.** When the run found no findings but
  failed to open or parse at least one input, it prints `INCOMPLETE SCAN, NOT A CLEAN BILL` with the
  audited and blocked counts. Relay that as the outcome too. The rule is the same one the denominator
  serves: the run cannot speak for a scope it never read, and the violation it missed may be sitting
  in the file it could not parse.
- **A clean bill needs frontmatter coverage when there was frontmatter to cover.** When a run
  with no finding and no unreadable input excluded every frontmatter candidate as non-loadable, it
  prints `NO FRONTMATTER AUDITED, NOT A CLEAN BILL` in place of the clean bill. Relay it as the outcome, and check that each plugin
  directory under the root sits at `plugins/<name>/` or holds `.claude-plugin/plugin.json`.
- **Say what was not read.** The block counts paths the walk could not open, settings files present
  but not valid JSON (whose rules were skipped entirely), and files an exclusion rule removed. Each
  of those is a hole in the denominator, and each belongs in the report next to the finding count.
- **Name the scopes this detector never opens**: managed-policy and enterprise settings, a
  `--settings` flag file, the start-directory copy. `audit-permission-state` owns the
  question of which scopes exist, and its `reference/criteria.md` §Scopes carries the dated record
  for the start-directory copy; this skill's silence about them is a boundary, not a result.

A user-global finding is reported the same as any other, but its remediation is the operator's: a
skill cannot write that file. When deciding where an approval-prompt grant lands, fetch
[permissions: permission system](https://code.claude.com/docs/en/permissions#permission-system)
live; when deciding whether anything prunes it, fetch
[permissions: manage permissions](https://code.claude.com/docs/en/permissions#manage-permissions)
live (as of 2026-11-04; recheck when the first section changes where a prompt approval is saved or
the second changes how saved rules are removed).

If a scope filter was given, run the full detector and present only the matching checks. P1, P2, P2b
and P4 are all emitted by the same rule scan, which runs over frontmatter `allowed-tools` and over
settings allow rules alike, so each of those four maps to `frontmatter` or `settings` by the source
the finding names rather than by its check id. P3 maps to `plugins`.

### Gate modes

The detector is advisory by default and a gate on request:

- `--check` exits 1 when any error-tier finding fired (P2, P2b, P4, P5), and 0 when none did.
- `--strict` does the same and adds the warning tier (P1, P3).
- Under either flag a `NOTHING TO AUDIT` result exits 2 rather than 0, and so does a run that saw no
  gate-firing finding but could not read one of its inputs. A scan that could not look is never a pass.
- Combining flags applies the strictest, whatever the order. An unrecognized argument prints usage on
  stderr and exits 2 without scanning, because a one-character typo in a CI invocation would otherwise
  leave the gate exiting 0 forever on a tree full of findings.
- The default report mode and `--count` are unchanged and always exit 0, however many findings print.

**A gate flag does not make this skill a fixer.** The skill stays report-only for the reason stated
above.

## Phase 2: Report

Present findings as the severity-rated table in
[reference/criteria.md](reference/criteria.md) "Output format". For each finding, give the concrete
recommendation from its check. For P1, match the platform reality the convention records: where
plugin `bin/` is not reliably on the Bash tool's PATH (see the convention's **Known gap** section),
prescribe the bundled-path grant that works today and an operator-setup note for the bare-name rule.
Do not unconditionally tell the operator to expose a bare command on PATH when that end state is not
yet reachable on the measured platform. Add an **Operator setup** note wherever a user-global
`~/.claude/settings.json` rule is required.

### Severity guide

| Severity | Criteria |
| --- | --- |
| error | Non-portable grant that leaks a username / breaks on other machines (P2, P2b), or a substitution token that stays literal in this rule's context so the grant never matches (P4), or an allow rule with text after its closing parenthesis (P5) |
| warning | Interpreter/runner-led grant whose broad forms auto mode drops, or an inert self-grant (P1, P3) |

P4 does not flag `${CLAUDE_PLUGIN_ROOT}` or `${CLAUDE_PLUGIN_DATA}` in a **plugin skill's**
`allowed-tools`; in a `Bash(...)` rule anywhere else it does. See [reference/criteria.md](reference/criteria.md), P4. When
deciding where those variables resolve, fetch
[plugins reference: where each variable resolves](https://code.claude.com/docs/en/plugins/manifest-reference#where-each-variable-resolves)
live (as of 2026-11-03; recheck when that section changes the fields a plugin variable resolves in).

A clean scan ("No fragile permission grants found.") is a valid outcome. Report it as such, with
the denominator beside it. `NOTHING TO AUDIT` is **not** that outcome; see "Report the denominator".

## Boundary, the built-in `/permissions` command

"Fix my permission rules" can mean this audit or the dialog that edits the rules.

- **`/permissions` (built-in command)**: the person's tool for editing rules; the model does not
  invoke it. When describing what it does, fetch its row in
  [commands: all commands](https://code.claude.com/docs/en/commands#all-commands) live (as of
  2026-11-03; recheck when that row changes or leaves the table).
- **This skill (marketplace plugin).** Audits grants for portability and auto mode durability
  across frontmatter and every settings scope, and writes nothing.

**Routing.** When a finding calls for adding, removing, or rewriting a settings rule, offer it to
the person: If /permissions is available in your session (gate basis: not gated in the extraction,
though a host may lack it; records in [reference/native-surfaces.md](reference/native-surfaces.md)),
you can run it instead of or alongside editing the file by hand. A grant
in `allowed-tools` frontmatter is outside the dialog; the finding's own remedy applies there. When
the caller passes `--unattended`, the run records the offer in its output
instead of asking; without that flag it asks.

**Mutation gate.** `/permissions` writes whichever scope the person edits. This skill never runs
it on the person's behalf.

**Availability is never assumed.** This section states what to do when the person can run
`/permissions`, never that it is present in their host. The four-part records live in
[reference/native-surfaces.md](reference/native-surfaces.md).

## Spoke paths

The `reference/` files write this skill's directory as `<skill-dir>`, which is
`${CLAUDE_SKILL_DIR}`. Put that path in place of the placeholder before running a command or writing
it into a brief. Those files arrive through the Read tool as plain bytes, so a `${…}` token in them
would reach the Bash tool unsubstituted, and the Bash tool's environment has no `CLAUDE_SKILL_DIR`
to expand it from. Basis: the plugins reference,
<https://code.claude.com/docs/en/plugins/manifest-reference#where-each-variable-resolves>, verified
2026-10-07; recheck when that table adds supporting files to where a `${…}` reference resolves.

## Next

- A finding needs its operative rule located across scopes:
  `/harness-config:audit-permission-state`.
- The question is config-file correctness rather than grant portability: `/harness-config:audit`.

## Consumer conventions

A consuming repo may declare, in its own `CLAUDE.md` (or the `AGENTS.md` a session reads natively,
whether in place of a `CLAUDE.md` or alongside one) / `.claude/rules/`, additional interpreter tokens
or path shapes it treats as fragile, or a documented exemption (e.g. a deliberately broad grant behind
a PreToolUse hook). Read those when present; this skill does not assume them.

**Three constraints on those declarations, because the repo being audited is the repo that writes
them.** The docs warn that a checked-in skill can grant itself tool access (Pointer: when weighing a
repository's own grants, fetch
[skills: pre-approve tools for a skill](https://code.claude.com/docs/en/skills#pre-approve-tools-for-a-skill)
live. As of: 2026-10-11. Recheck trigger: that section drops its warning about reviewing checked-in
skills' grants), and an exemption read out of the audited tree is input from the subject of the
audit:

1. **Disclosure.** Every declaration the run read is named in the report, with the file it came from
   and what it changed, whether or not it altered a single finding. A declaration that was read and
   left no trace in the report is indistinguishable from one that was never read.
2. **Narrowing only in the report, never in the finding set.** A declaration may ADD fragile tokens
   or path shapes. It may never delete a finding. An exemption downgrades a finding's severity and
   annotates it `exempt — <declaration source>: <stated reason>`; the row stays in the table and
   stays in the counts.
3. **A suppressed report must not read like a clean one.** If every finding in a run is exempted,
   the report says so explicitly, "N finding(s), all exempted by consumer declaration", and does
   not print a clean bill.

