Arguments. [--unattended] [--scopes] [--entry-diff] [--lint] [--managed] [--block] [--oracle] [--critique]. Full form: (none) every read-only stage | [--scopes] [--entry-diff] [--lint] [--managed] [--block] narrow | [--oracle] [--critique] priced
Purpose
For "where is this rule written", use /permissions. This skill answers a different question: it
computes the merged allow/ask/deny outcome itself, locally and off a live session, as line records a
script can read, and it reports a scope it could not read apart from one that was empty.
- Pointer: when deciding whether a built-in surface already exports the merged set, fetch
CLI commands and the
/permissionsrow of commands: all commands live. - As of: 2026-11-03
- Recheck trigger: a release note mentions a permissions export or a
/permissionsexport action, or either section adds one.
It answers a question the siblings do not. audit-permission-grants asks whether the grants you
wrote are durable and portable; audit asks whether your config files are correct. This
skill asks what is in effect: which scopes exist on this machine, which of them this reader
could actually open, and what each one holds.
Scope boundary (route out)
- Grant portability and auto-mode durability (P1/P2/P3) →
harness-config:audit-permission-grants. - Settings-file correctness outside the permission plane (schema and unknown keys, baseline
deny/ask presence, deny-rule placement, MCP, hooks, plugin drift) →
harness-config:audit. The permission plane's own dead config, thedisableAutoModetype trap, and rules that cannot match stay here, in Phase 4: they are read across all five scopes at once, which is this skill's asset and not something a project-scope reader can do. - The instruction layer (CLAUDE.md, a natively read AGENTS.md, rules, auto-memory) → the
harness-memoryplugin.
Boundary, native Claude Code surfaces
Two native surfaces act on the same permission rules this skill reports, so "fix my permissions" can mean any of the three.
fewer-permission-prompts(bundled skill): writes an allowlist into project settings to cut prompts. Either the model or the person may run it./permissions(built-in command). The person's interactive editor for rules by scope and for auto mode's classifier rules. This skill never runs it.- This skill (marketplace plugin). Computes the effective merged set across every scope, off a live session, with source, precedence, auto mode drops, and dead config. It writes nothing.
Routing. When the bundled fewer-permission-prompts skill resolves in this session, prefer it
for reducing prompts by writing an allowlist; prefer this skill to see what is in effect. When the
report ends with a rule the person wants added, removed, or moved, offer it to the person:
If /permissions is available in your session (gate basis: it varies by version and host; records
in reference/native-surfaces.md), you can run it to view and edit
these rules interactively. When the caller passes
--unattended, the run records that offer in its output instead of asking;
without that flag it asks.
Mutation gate. fewer-permission-prompts writes project settings, and /permissions writes
whichever scope the person edits. This skill never chains into either on its own behalf.
Availability is never assumed. Settings, version and host decide whether either surface resolves; this section states what to do when they resolve, never that they are present. The four-part records live in reference/native-surfaces.md.
Report-only, permanently
This skill writes no settings file, in any scope, under any flag. That is the contract, and it
holds including under --oracle. It is not the same as writing nothing at all: --oracle spawns a
real claude -p session, and a session rewrites ~/.claude.json and adds project, session-env,
security, subagent and backup state under your config directory. The flag prints that before it
spawns anything. Every other action writes nothing anywhere. This skill treats managed policy as
read-only by construction: it reads the managed sources and never authors them.
- Pointer: when deciding which managed sources exist and who can write each, fetch managed settings: where each mechanism stores the policy live.
- As of: 2026-11-10
- Recheck trigger: that section adds a managed mechanism or a store a plugin or user can write.
Arguments
Parse $ARGUMENTS. Flags narrow; they never widen.
- (no argument): every read-only stage, in order, through one entry point. See "Run it" below.
--unattended, anywhere: the caller declares nobody is present, which changes only the/permissionsoffer (see "Boundary" above). It is not a stage flag andaudit.shrefuses it: drop it from the arguments "Run it" passes.--scopes: surface records only, no rule inventory and no downstream stage. Use when the question is "which scopes exist and which could you read", not "what is in them".--entry-diff: inventory, merge, and the auto-mode entry diff (Phase 3).--lint: inventory and the permission-plane lint (Phase 4).--managed: inventory and the managed-conformance report (Phase 6).--block: theautoModeblock lint (Phase 5). Reads the CLI, not the inventory, so it runs alone.--oracle: with--entry-diff, cross-check the prediction against the harness's own drop narration. Spawns a realclaude -psession; never fires without this flag. See its cost notice, which the run prints before anything is spawned.--critique: with--block, addclaude auto-mode critique. Slow, and it truncates or returns nothing while still exiting 0, so its result is reported as unavailable rather than as clean.
Run it
One entry point runs each stage once and fans the inventory out, instead of walking every scope once
per pipeline (with --unattended dropped from the arguments):
bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-permission-state/scripts/audit.sh" $ARGUMENTS
The phases below document what each stage decides and how to read it. Every stage script stays
independently invocable and composes on its own, which is what draft-auto-mode-rules and
audit-pass rely on; audit.sh is a convenience caller, never a gateway.
Read the status= token on every summary line before the counts above it. status=read means
the stage saw every scope; status=incomplete means at least one could not be opened and the counts
cover only what was read. A finding count of zero under status=incomplete is not a clean bill.
Phase 1: Discover and inventory
Stage: permission-state.sh, the deterministic spine every other stage consumes. It emits one record
per line:
<scope> <surface> <status> <path> one per settings surface
rule <scope> <surface> <kind> <rule text> one per allow/ask/deny entry
NOTE: <text> anything the operator must know
| Field | Values |
|---|---|
scope |
managed, user, project, local, startdir-local |
surface |
file, dropin-dir, dropin-file:<name>, registry, plist (managed); toplevel (project, see Scopes); settings elsewhere |
status |
present, absent, unreadable, invalid-json, skipped, not-applicable |
kind |
allow, ask, deny |
Phase 2: Merge into the effective set
Stage: permission-merge.sh, fed the inventory. It reports what is actually in force, each rule
carrying its provenance. It passes the records above through, then appends:
CAVEAT: <text> what bounds the claim
effective <kind> scopes=<a,b> precedence_basis=<token> <rule> one per live rule
inert <kind> scopes=<a,b> outranked_by=<kind> <rule> one per beaten entry
carveout <kind> source=<scope>:<surface> [bare] <rule> one per ! Read/Edit rule
These mechanics decide those records, and conflating them produces confident wrong answers:
- The merge treats rules as merging across scopes, never overriding, so the same rule in the
same list at two scopes has no winner. Both are live, and
scopes=names every contributor. Never report one of them as having overridden the other. - The merge decides kind by the fixed evaluation order
scripts/permission-merge.shencodes, across scopes, and records which rule made another inert. Thatinertrecord is what answers "why is my allow rule ignored". When checking that order and whether scope rank enters it, fetch settings: permission rules combine differently than you expected live (as of 2026-11-03; recheck when that section changes the evaluation order or how scopes combine). - The merge treats a bare tool name as reaching every call of that tool. A whole-tool deny
makes every other rule naming that tool inert, other denies included, with the one exception
reference/criteria.mdnames. A whole-tool ask leaves no scoped allow for that tool in effect. Both print aNOTE:naming the tool. - The merge keeps a
!carve-out inside its own source. A deny or askReadorEditrule whose pattern starts with!is reported as acarveoutrecord naming the one file it came from, never merged across scopes, so never read it as reopening a path another file blocks. A carve-out whose pattern is a bare!is taggedbare, and its effect is a known gap the merge does not model.- Pointer: when you need what a carve-out reaches, fetch permissions: Read and Edit live.
- As of: 2026-10-10
- Recheck trigger: that section changes what a carve-out reaches, or starts covering a bare
!pattern.
reference/criteria.md maps every precedence_basis token to the docs section it follows from,
with that record's as-of date and recheck trigger, and states the two standing bounds the run
prints.
Phase 3: What entering auto mode drops
This stage predicts which of your broad allow rules auto mode sets aside on entry, with no notice, until the session leaves auto mode again, and which carry over.
It describes a transition most run shapes never make, so state the precondition when you report
it. The run prints, as a DIFF-NOTE, the run shapes we treat as starting in auto mode; carry it
rather than presenting the diff as unconditional. reference/criteria.md §"The auto-mode entry
diff" and §"The precondition: which sessions enter auto mode at all" hold the pointers.
Stage: automode-entry-diff.sh, fed the merge.
DIFF-NOTE: <text> classifyAllShell state, bounds
entry-diff dropped class=<class> scopes=<a,b> <rule> dropped on entry
entry-diff suspended reason=classifyAllShell ... suspended while auto mode is active
entry-diff kept scopes=<a,b> <rule> carries over
entry-diff summary allow_before=<n> dropped=<n> suspended=<n> kept=<n>
- The diff covers allow rules only. We treat deny and ask as evaluated before the classifier in every mode, so they are not part of this diff. Do not report them as "surviving".
- Neither label is permanent.
droppedandsuspendedboth describe what is in force while auto mode is active; the rules are restored when the session leaves it, and nothing edits a settings file. The two labels are kept apart because the remedies differ: adroppedrule is fixable by narrowing that rule, whilesuspendedis a global switch no rule edit reaches. classnames the reason:blanket,interpreter-wildcard,package-manager-run,agent, ormonitor. The three shell shapes come fromlib/permission-patterns.sh, the vocabularyaudit-permission-grantscheck P1 also scans with;agentandmonitorare whole-tool classes this script tests on the tool token,monitorwith the version boundreference/criteria.md§"The auto-mode entry diff" records.autoMode.classifyAllShellinverts the answer wholesale. The stage treats it, when true, as suspending every Bash and PowerShell allow rule, so narrow rules do not carry over. It resolves the key only from the scopes it treats the classifier as reading, so a project- or local-scope copy is reported inert rather than obeyed.reference/criteria.mdholds the pointers.--oracleis opt-in and priced. It spawns a realclaude -psession to corroborate the prediction. Measured cost: your settings files are untouched, but~/.claude.jsonis rewritten and project, session-env, security and subagent state appear under your config directory. A capture that yields nothing is unavailable, never an empty drop set.
Phase 4: Configuration that is written but never read
The permission plane accepts things it silently ignores. This finds them across every scope at once, before a session starts:
Stage: permission-plane-lint.sh, fed the inventory.
finding <severity> [<check>] <scope> <detail>
lint summary findings=<n> checks_run=<n> status=<read|incomplete>
Eleven checks: three C2-* dead-config gates, C5-disableType, and seven C6-* rules-that-cannot-match, including a malformed Tool(content) rule and an uncompilable Read/Edit path.
reference/criteria.md maps each to the docs section it follows from and lists the legitimate rule
shapes the checks are written NOT to flag.
C5-disableTypeis the one to read first. It flags any value other than the string"disable"as a false lockout: valid JSON the operator believes locks auto mode out. When deciding which value locks it out, fetch settings reference:disableAutoModelive (as of 2026-11-03; recheck when that section changes the value that disables auto mode).- The three
C2gates stay separate findings. Different scope sets, different version histories: an operator who fixed one and saw the count drop would reasonably believe they had fixed all three. findings=0is a clean bill only understatus=read. Understatus=incompletea scope could not be opened and was never linted; the accompanyingLINT-NOTEnames which.- Advisory: the lint always exits 0 when it ran. Exit 2 means it could not run at all, never "nothing found".
Phase 5: The autoMode classifier block
A different surface from everything above: four natural-language sections an LLM classifier reads, not permission rules the harness matches. Independent of the pipeline, it reads the CLI, not stdin:
bash "${CLAUDE_PLUGIN_ROOT}/skills/audit-permission-state/scripts/automode-block-lint.sh" [--critique]
C4-defaults: a customized section that omits"$defaults". We treat such a section as replacing the built-in list rather than adding to it, so the finding names how many built-in entries are gone.reference/criteria.md§"TheautoModeblock lane" holds the pointer.C2b-contradiction: the same subject inallowand in a deny section.C3-shadowed: an entry an earlierhard_denyalready forecloses, so it can never fire.--critiquesurfacesclaude auto-mode critique, wrapped and never replaced. It owns the semantic judgment. What this adds is honesty about it: measured across three consecutive runs on one unchanged config, output was truncated mid-sentence twice and empty once, exiting 0 every time. A mid-sentence cut is reported as truncated; an empty result says "critique returned nothing; run it yourself" rather than implying your rules are clean.
This lane is optional. It needs python3 because
claude auto-mode config emits raw control characters inside string values. jq rejects the output
outright, and no line-oriented POSIX filter can repair it, since the offending byte is a raw line feed
inside a string. Absent python3 or claude, the lane prints a visible skip notice and exits 0; every
other stage still runs.
Exit status is never trusted here. A run that exits 0 having produced nothing is reported
status=unavailable with an explicit "this is NOT a clean bill". The distinction between "your block
is clean" and "the block was never read" is the whole point.
Phase 6: What managed policy actually enforces
An administrator deploys managed policy believing it is policy. Some of it is; some is not, and
nothing surfaces which. Stage: managed-conformance.sh, fed the inventory.
managed enforced deny <rule>: the strongest thing an administrator can write. We treat a managed permission rule as outranked by no level, command line included, and a tool denied at any level as allowed at none.managed loosenable rule …: the interaction that surprises people, reported when a lower-scope rule of an earlier-evaluated kind outranks a managed rule, because an administrator reads the managed rule as policy. When deciding how managed rules rank and evaluate, fetch permissions: settings precedence live (as of 2026-11-03; recheck when that section changes managed rank or the evaluation order).managed loosenable autoMode: we report a managedautoModesection as additive, not a policy boundary, since a developer's own entries can loosen it.managed loosenable lockout:disableAutoModeset to anything but the string"disable".
reference/criteria.md §"Managed policy, and what it does not buy" holds the pointers for all
four.
This report never prescribes. It says what the consumer's own policy does and does not achieve; every rule string it prints came from a file it read. It ships no security floor of its own.
Completeness is bounded on every run. "Managed" means the local admin surfaces only. We do not
fold the server-managed cache into the effective set, and do not treat it as the live policy. When
deciding where the cache lives and how current it is, fetch
server-managed settings: fetch and caching behavior
live (as of 2026-11-03; recheck when that section changes where the cache is kept or how it is
refreshed). A surface that could not be read gets its own note saying so, because an administrator
reading silence as "no policy deployed" is the failure this report exists to prevent. The note
routes that diagnosis to the Organization policy line in /status and claude doctor.
- Pointer: for where a managed source and a policy that failed to load are shown, see
Read the source in /status
and the
/statusrow of All commands. - As of: 2026-09-28
- Recheck trigger: those pages drop the Organization policy line or stop naming
/statusas the place a managed source is shown.
Reading the output honestly
Interpret and report the records below; the judgment is over the consumer's configuration, never over anything this skill produced. The status vocabulary carries the whole point of the skill, so do not collapse it in the report:
absentmeans looked and found nothing.skippedmeans could not look. Never present askippedsurface as "no policy". Say the surface was not read and why. The script emits aNOTE:naming the reason every time.- Every scope and every managed surface emits a record on every OS, including the ones that do
not apply here (
not-applicable). A surface missing from the output is a defect in this reader, not evidence about the machine. managedmeans the LOCAL managed surfaces. The script does not fold the server-managed cache at~/.claude/remote-settings.jsoninto the effective set, and treats the Organization policy line in/statusas the failure read. The script says so on every run; carry it into the report rather than implying completeness.- An
askfinding names where the contract lives: the auto mode config page, and the upstream issue #83766 against it. Carry the caveatreference/criteria.md§"Ask rules under auto mode" words, with its pointer and dated record, when reporting anaskresult, and point atpermissions.denywhere the outcome must hold regardless. invalid-jsonis notabsent. A malformed settings file contributes no rules to the inventory. Report the parse failure, not an empty scope, and do not describe a managed parse failure as silent non-enforcement: we treat an unparsable managed source as stopping Claude Code at startup, on the versions the pointer names, and an unparsable user, project, or local file as a reported settings error.- Pointer: for managed sources that fail to parse, fetch managed settings: find entries Claude Code dropped live; for other settings files, fetch settings: fix a broken settings file live.
- As of: 2026-10-11
- Recheck trigger: either section changes what Claude Code does when a settings source fails to parse.
Scopes
Five: managed, user, project, local and startdir-local. local and startdir-local are
the two easy to get wrong; when deciding where the local file is read from, fetch
settings: where Claude Code keeps the local file in a git repository
live (as of 2026-11-04; recheck when that section changes where the local or shared file is kept).
The reader takes its own working directory as the session's primary working directory, the one input
for project and local. Run it from the directory the session started in (or last moved to with
/cd). Below the repository root it reads two shared files, project settings from its own
directory and project toplevel from the root, and no other. So after an in-session Bash cd, the
start directory's file is not read unless it is the root's: a session started in repo/a that ran
cd b gets repo/a/b and the root, never repo/a. Both files it reads feed the merge, and the set
can over-report the one not in force. Say which directory the session started in when that decides
the answer. When judging whether a cd still carries over, fetch
tools reference: what persists between commands
live (as of 2026-11-04; recheck when that section changes what a cd does to the working directory).
managed
is four admin surfaces per OS, not one file, plus a remote-cache record for the server-managed
cache that is not folded into the effective set. reference/criteria.md §Scopes has the full table
and the dated record.
The reader resolves every condition we treat as keeping the local file beside
.claude/settings.json instead, and the basis line names which applied. One further case, the
Agent SDK's resolveSettings() helper, is stated rather than detected, because it is a helper's
behavior and not a session property. reference/criteria.md §"The four start-directory
conditions, and the one that is not detectable" holds the list and its pointer.
A cloud session reads a different scope set, and the run says so. We treat a user-scope record
in a cloud session as describing the container, not the operator. The reader detects a cloud
session by CLAUDE_CODE_REMOTE, the only entrypoint variable it branches on.
reference/criteria.md §Scopes holds both dated records.
Prerequisites
jq, required for correctness. Absent, the script stops at the entry point withERROR: jq requiredand exit 2, followed by the install command for the platform when it finds one. Report the environment gap and that install line; do not report a clean bill.reg(Windows) anddefaults(macOS), required for an optional feature. Absent, that one managed surface isskippedwith a visible notice and everything else still runs.
Gotchas
Failure modes that produce a confidently wrong answer, and the honest limits of what has been verified on real hardware, are in reference/gotchas.md. Read it when a result looks wrong, when debugging a stage by hand, or before trusting a managed surface on macOS or Linux.