From 9e38fd7eeb7cd3a7b8d6ea8aa99d631ed40623c5 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 00:28:59 -0400
Subject: [PATCH 1/8] feat(claude-config-audit): add permission-hygiene grant
 audit + convention

Add a durable guardrail against fragile Claude Code permission grants.

Enforceable check: a new `permission-hygiene` skill whose deterministic
`permission-rule-check.sh` detector scans skill/command/agent frontmatter
`allowed-tools` and settings.json/settings.local.json `permissions.allow`,
flagging three anti-patterns and recommending the bare-command-on-PATH pattern:

- P1 interpreter-wildcard / blanket allow rules that Claude Code drops on
  entering auto mode (Bash(*), Bash(python*), Bash(bash <path>*), package-manager
  runners, Bash(*.py:*)); narrow rules like Bash(npm test) carry over and are
  not flagged.
- P2 hardcoded absolute machine/user paths (Bash rules match literally with no
  ~/$HOME/env expansion).
- P3 a plugin settings.json that declares an inert `permissions` block (only
  agent/subagentStatusLine are supported), so the operative rule must be added
  by the operator to user-global ~/.claude/settings.json.

Ships with a 27-check contract test (positive + negative fixtures, including the
narrow-rule-not-flagged case), reference/criteria.md, and evals/evals.json.
settings.local.json is parsed for permissions.allow only, never echoed. Scope vs
settings-audit (file correctness) is explicit and routes out.

Convention: docs/conventions/permission-rule-hygiene (README + CHANGELOG) states
the principle, the three anti-patterns, the correct bare-name+PATH / plugin-bin
pattern, and the operator-setup boundary, each with official-doc citations; the
skill's criteria link to it rather than restating.

Detector and fixtures assemble machine-path strings from fragments and the docs
use <name> placeholders so no contiguous machine-path literal sits in a committed
file, keeping the repo's own machine-specific-path lane clean.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 README.md                                     |   2 +-
 .../permission-rule-hygiene/CHANGELOG.md      |  17 ++
 .../permission-rule-hygiene/README.md         | 119 +++++++++++
 .../.claude-plugin/plugin.json                |   6 +-
 plugins/claude-config-audit/README.md         |  25 ++-
 .../skills/permission-hygiene/SKILL.md        |  80 +++++++
 .../permission-hygiene/evals/evals.json       |  65 ++++++
 .../permission-hygiene/reference/criteria.md  |  96 +++++++++
 .../scripts/permission-rule-check.sh          | 202 ++++++++++++++++++
 .../scripts/permission-rule-check.test.sh     | 179 ++++++++++++++++
 10 files changed, 784 insertions(+), 7 deletions(-)
 create mode 100644 docs/conventions/permission-rule-hygiene/CHANGELOG.md
 create mode 100644 docs/conventions/permission-rule-hygiene/README.md
 create mode 100644 plugins/claude-config-audit/skills/permission-hygiene/SKILL.md
 create mode 100644 plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
 create mode 100644 plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
 create mode 100755 plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
 create mode 100755 plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh

diff --git a/README.md b/README.md
index 0ebaaa98d..c58bda63d 100644
--- a/README.md
+++ b/README.md
@@ -41,7 +41,7 @@ Browse and manage with `/plugin`. To refresh after updates: `/plugin marketplace
 | [`docs-hygiene`](plugins/docs-hygiene) | Skills | Documentation-hygiene toolkit of five skills: `/docs-hygiene:compress` (flavor-trim markdown behind a semantic-diff safety net), `/docs-hygiene:declutter` (classify markdown noise, read-only), `/docs-hygiene:extract-ssot` (deduplicate repeated content into a single source of truth), `/docs-hygiene:encapsulation-audit` (detect citations into skill-private surfaces), and `/docs-hygiene:rename-references` (sweep stale references after renames). |
 | [`fable-5-playbook`](plugins/fable-5-playbook) | Skill | Ships Claude Fable 5's operating doctrine as an on-demand knowledge skill — core standing instructions plus twelve trigger-routed chapters (calibration, reasoning moves, planning, debugging, orchestration, verification, recovery, trust boundaries, and more) and an Opus-adaptation chapter for non-Fable models. |
 | [`firecrawl`](plugins/firecrawl) | Skill | Web scraping, search, crawling, URL discovery, browser interaction, and local file parsing through the `firecrawl-cli` binary — results written to disk and read back selectively to keep large pages out of context, plus a gated maintainer update flow tracking the upstream CLI and skill source. |
-| [`claude-config-audit`](plugins/claude-config-audit) | Skills | Keeps a repo's Claude Code configuration healthy via three report-first audit skills: `settings-audit` (config files vs upstream truth, with live plugin-drift detection), `memory-health` (CLAUDE.md / rules / auto-memory against official-doc criteria), and `automation-deep-dive` (evidence-gated verdicts on automation gaps). |
+| [`claude-config-audit`](plugins/claude-config-audit) | Skills | Keeps a repo's Claude Code configuration healthy via four report-first audit skills: `settings-audit` (config files vs upstream truth, with live plugin-drift detection), `memory-health` (CLAUDE.md / rules / auto-memory against official-doc criteria), `automation-deep-dive` (evidence-gated verdicts on automation gaps), and `permission-hygiene` (allow-rule / allowed-tools grants for auto-mode durability and machine portability). |
 | [`work-items`](plugins/work-items) | Skill | Manages development work items through a provider-neutral tracker seam (GitHub the bound adapter today): dashboard, taxonomy-labeled creation, a race-safe assignee-plus-lease claim protocol for multi-agent pickup, recurring-schedule checks, TODO scanning, stale-lease auditing, plan decomposition into vertical slices, and structured triage. |
 | [`discovery`](plugins/discovery) | Skills | Structured discovery before changes. Ships four skills: `/discovery:explore` and `/discovery:explore-deep` (six-dimension codebase exploration, inline or in a forked subagent) plus `/discovery:research` and `/discovery:research-deep` (three-phase multi-source external research with source tiers, falsification, and recency gates). |
 | [`playwright`](plugins/playwright) | Skill | Live E2E browser automation through Microsoft's `@playwright/cli` — named sessions, accessibility-ref snapshots (click/fill by ref), screenshots, console/network capture, mocking, tracing, video, and auth state, with artifacts written to disk so only paths enter context, plus Windows/orchestrator overlays and a gated maintainer update flow tracking the upstream npm skill. |
diff --git a/docs/conventions/permission-rule-hygiene/CHANGELOG.md b/docs/conventions/permission-rule-hygiene/CHANGELOG.md
new file mode 100644
index 000000000..9fa156e65
--- /dev/null
+++ b/docs/conventions/permission-rule-hygiene/CHANGELOG.md
@@ -0,0 +1,17 @@
+# Permission Rule Hygiene Convention — Changelog
+
+Notable changes to the permission-rule-hygiene convention. The convention states a principle and three
+anti-patterns; it is enforced by the `claude-config-audit` plugin's `permission-hygiene` skill (checks
+P1/P2/P3), whose detector and criteria version independently of this document.
+
+## 1.0 — 2026-07-14
+
+Initial published convention.
+
+- Principle: the operative allow-rule for a guarded code-execution helper must be a narrow,
+  machine-independent, bare-command rule the operator adds to user-global settings.
+- Anti-pattern 1 — interpreter-wildcard / blanket allow rules dropped in auto mode.
+- Anti-pattern 2 — hardcoded absolute machine/user paths (Bash rules match literally, no expansion).
+- Anti-pattern 3 — assuming a skill or plugin can self-grant an auto-mode-gated action class.
+- Correct pattern: bare command on the Bash tool PATH (pre-plugin PATH shim, post-migration plugin
+  `bin/`) allowed narrowly by bare name, with an operator-setup boundary note.
diff --git a/docs/conventions/permission-rule-hygiene/README.md b/docs/conventions/permission-rule-hygiene/README.md
new file mode 100644
index 000000000..ec36ebdcd
--- /dev/null
+++ b/docs/conventions/permission-rule-hygiene/README.md
@@ -0,0 +1,119 @@
+# Permission Rule Hygiene Convention
+
+A marketplace-wide convention for writing Claude Code permission grants that actually take effect —
+specifically, grants for the auto-mode-gated action classes (arbitrary code execution) that a skill,
+command, or plugin wants to run without a prompt.
+
+The principle: **the operative allow-rule for a guarded code-execution helper must be a narrow,
+machine-independent, bare-command rule that the operator adds to user-global settings — never an
+interpreter-wildcard grant, never a hardcoded machine path, and never a self-granted rule a skill or
+plugin ships expecting it to work.** The three anti-patterns below each break that in a different way;
+the [correct pattern](#the-correct-pattern) fixes all three at once.
+
+Enforced by the [`permission-hygiene`](../../../plugins/claude-config-audit/skills/permission-hygiene)
+skill in the `claude-config-audit` plugin, which scans skill/command/agent frontmatter `allowed-tools`
+and `settings.json` / `settings.local.json` `permissions.allow` and flags each anti-pattern (checks
+P1/P2/P3).
+
+## Why this convention exists
+
+Running this convention's own detector against this marketplace surfaced six pre-existing
+interpreter/runner-led frontmatter grants (shapes like `Bash(bash <script>:*)`, `Bash(bash <dir>/*)`,
+and `Bash(npx:*)`) across unrelated plugins — none of them the portable bare-name pattern, and the
+broad forms among them (a globbed script target, a package runner) are exactly what auto mode drops.
+When a grant is dropped the failure is silent: it parses, looks correct, and does nothing the moment
+the session enters auto mode, so the action falls through to the classifier and can be denied even when
+the operator intended to pre-approve it. A convention plus an enforceable check is the durable fix.
+
+## Anti-pattern 1 — interpreter-wildcard / blanket allow rules (dropped in auto mode)
+
+On entering [auto mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode),
+Claude Code **drops broad allow rules that grant arbitrary code execution**. Per the official decision
+order:
+
+> On entering auto mode, broad allow rules that grant arbitrary code execution are dropped:
+> Blanket `Bash(*)` or `PowerShell(*)`; Wildcarded interpreters like `Bash(python*)`; Package-manager
+> run commands; `Agent` allow rules. Narrow rules like `Bash(npm test)` carry over. Dropped rules are
+> restored when you leave auto mode.
+> — [permission-modes](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode)
+> ("How the classifier evaluates actions")
+
+The [auto-mode configuration reference](https://code.claude.com/docs/en/auto-mode-config#route-all-shell-commands-through-the-classifier)
+restates it and adds that `autoMode.classifyAllShell: true` suspends even the narrow shell allow rules:
+
+> Auto mode suspends only the broad rules that grant arbitrary code execution, such as `Bash(*)` or
+> wildcarded interpreters.
+
+So a frontmatter grant such as `allowed-tools: ['Bash(python "*helper.py":*)']`, or any
+`Bash(python*)` / `Bash(node*)` / `Bash(bash *)` / `Bash(*.py:*)` / `Bash(sh -c*)` / package-manager
+runner (`npx`, `uvx`, `pipx run`, `pnpm dlx`, …), silently grants nothing under auto mode. The action
+then depends entirely on the classifier. Empirically, a guarded merge helper granted this way was
+denied even when invoked bare.
+
+## Anti-pattern 2 — hardcoded absolute machine/user paths
+
+Bash permission rules match the command string **literally**. Per
+[permissions](https://code.claude.com/docs/en/permissions#wildcard-patterns), a Bash rule is a glob
+over the literal command — there is no `~`, `$HOME`, or environment-variable expansion (the `~/` and
+`//` home/absolute anchors documented under
+[Read and Edit](https://code.claude.com/docs/en/permissions#read-and-edit) are gitignore-style path
+anchors for the file tools, not shell-command expansion). A rule like
+`Bash(/c/Users/<name>/.agents/skills/merge/x.sh:*)`:
+
+- breaks on any other machine or username, and after the skill migrates into a plugin (the install
+  path changes), and
+- leaks a username into version control.
+
+The one substitution that *is* expanded in `allowed-tools` is `${CLAUDE_PROJECT_DIR}` (Claude Code
+v2.1.196+, per [skills](https://code.claude.com/docs/en/skills)) — but that anchors to the consuming
+project, not to a portable command, so it still isn't the right tool for a shared code-execution
+helper.
+
+## Anti-pattern 3 — assuming a skill or plugin can self-grant
+
+Three official constraints mean the operative allow-rule cannot be shipped by the skill or plugin:
+
+- **Skill `allowed-tools` is skill-scoped and (per anti-pattern 1) ineffective for auto-mode-gated
+  action classes.** It "grants permission for the listed tools while the skill is active … It does not
+  restrict which tools are available" —
+  [skills](https://code.claude.com/docs/en/skills) — but auto mode still drops the broad/interpreter
+  shapes.
+- **A plugin cannot ship permission rules.** A plugin's `settings.json` supports "Only the `agent` and
+  `subagentStatusLine` keys" —
+  [plugins-reference](https://code.claude.com/docs/en/plugins-reference) (Settings row). A
+  `permissions` block placed there is inert.
+- **An agent editing its own settings to self-grant is blocked.** `defaultMode: "auto"` is ignored
+  from project/local settings "so a repository cannot grant itself auto mode" and `.claude/` writes are
+  a protected path routed to the classifier —
+  [permission-modes](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode).
+
+So the operative rule must be added **by the operator** to user-global
+`~/.claude/settings.json`.
+
+## The correct pattern
+
+Expose the guarded helper as a **stable bare command on the Bash tool's PATH**, then allow that bare
+name narrowly:
+
+1. **Put the helper on PATH under a stable bare name.**
+   - Pre-plugin: a small PATH shim in a directory already on your PATH (e.g. `~/.local/bin`, if it is
+     on your PATH) that delegates through `$HOME` to the skill's self-locating wrapper.
+   - Post-migration: the plugin's `bin/` directory — "Executables added to the Bash tool's `PATH` …
+     invokable as bare commands in any Bash tool call while the plugin is enabled" —
+     [plugins-reference](https://code.claude.com/docs/en/plugins-reference) (Executables row).
+   - Wrappers self-locate their real directory (e.g. `readlink -f`) so they work via direct, shim, or
+     symlink invocation.
+2. **Allow the bare name, narrowly.** `Bash(babysit_merge.sh:*)` — a narrow rule that carries over
+   into auto mode exactly like `Bash(npm test)`, is machine/username-independent, and is identical
+   before and after plugin migration.
+3. **State the operator-setup boundary.** The skill/plugin documents an "Operator setup" note telling
+   the operator to add the bare-name rule once to `~/.claude/settings.json`, and never relies on
+   interpreter-wildcard `allowed-tools` for auto-mode-gated actions.
+
+## Sources
+
+- Auto-mode drop behavior and decision order — [permission-modes](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode)
+- `classifyAllShell`, narrow-rule carryover — [auto-mode-config](https://code.claude.com/docs/en/auto-mode-config#route-all-shell-commands-through-the-classifier)
+- Literal matching, wildcard / `:*` semantics, process-wrapper stripping — [permissions](https://code.claude.com/docs/en/permissions#permission-rule-syntax)
+- `allowed-tools` scope and `${CLAUDE_PROJECT_DIR}` substitution — [skills](https://code.claude.com/docs/en/skills)
+- Plugin `bin/` on PATH and the `agent`/`subagentStatusLine`-only `settings.json` — [plugins-reference](https://code.claude.com/docs/en/plugins-reference)
diff --git a/plugins/claude-config-audit/.claude-plugin/plugin.json b/plugins/claude-config-audit/.claude-plugin/plugin.json
index d4fd29b7f..f023b59b9 100644
--- a/plugins/claude-config-audit/.claude-plugin/plugin.json
+++ b/plugins/claude-config-audit/.claude-plugin/plugin.json
@@ -1,12 +1,12 @@
 {
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "claude-config-audit",
-  "version": "0.2.0",
-  "description": "Three audit skills for a repo's Claude Code configuration: settings-audit (settings.json / .mcp.json / hooks / plugins / permissions drift), memory-health (CLAUDE.md, rules, and auto-memory against official-doc criteria), and automation-deep-dive (evidence-gated verdicts on automation gaps).",
+  "version": "0.3.0",
+  "description": "Four audit skills for a repo's Claude Code configuration: settings-audit (settings.json / .mcp.json / hooks / plugins / permissions drift), memory-health (CLAUDE.md, rules, and auto-memory against official-doc criteria), automation-deep-dive (evidence-gated verdicts on automation gaps), and permission-hygiene (allow-rule / allowed-tools grants for auto-mode durability and portability).",
   "author": {
     "name": "Melodic Software",
     "email": "info@melodicsoftware.com"
   },
   "license": "MIT",
-  "keywords": ["settings", "configuration", "memory", "claude-md", "hooks", "plugins", "automation", "audit", "maintenance", "skill"]
+  "keywords": ["settings", "configuration", "memory", "claude-md", "hooks", "plugins", "permissions", "automation", "audit", "maintenance", "skill"]
 }
diff --git a/plugins/claude-config-audit/README.md b/plugins/claude-config-audit/README.md
index 6662f38c6..09037d5ff 100644
--- a/plugins/claude-config-audit/README.md
+++ b/plugins/claude-config-audit/README.md
@@ -1,6 +1,6 @@
 # claude-config-audit
 
-A Claude Code plugin bundling three audit skills for one cohesive capability: keeping a repo's Claude
+A Claude Code plugin bundling four audit skills for one cohesive capability: keeping a repo's Claude
 Code configuration healthy. Each skill answers a different question about the same surface:
 
 | Skill | Question it answers |
@@ -8,9 +8,11 @@ Code configuration healthy. Each skill answers a different question about the sa
 | `/claude-config-audit:settings-audit` | Are the configuration FILES (`settings.json`, `settings.local.json`, `.mcp.json`, hooks, plugins, permissions) correct against upstream truth? |
 | `/claude-config-audit:memory-health` | Is the instruction/memory layer (`CLAUDE.md`, `CLAUDE.local.md`, `.claude/rules/`, auto-memory) healthy against official-doc criteria? |
 | `/claude-config-audit:automation-deep-dive` | Is the configured automation SET the right set — are there genuine gaps, judged against the enforcement hierarchy? |
+| `/claude-config-audit:permission-hygiene` | Are the permission GRANTS (`allowed-tools`, `permissions.allow`) portable and durable — do they survive auto mode, work across machines, and live where they can take effect? |
 
-All three default to report-only; mutations (`--fix`, the `fix` action, `--implement`) require
-explicit opt-in and per-item user approval.
+All default to report-only; mutations (`--fix`, the `fix` action, `--implement`) require explicit
+opt-in and per-item user approval. `permission-hygiene` is report-only (its correct remediation is
+operator-manual).
 
 ## What each skill does
 
@@ -58,6 +60,23 @@ verdict is REJECT — a clean bill of health is a valid outcome.
 /claude-config-audit:automation-deep-dive --implement   # implement user-approved items
 ```
 
+### permission-hygiene
+
+Audits permission GRANTS (not file correctness — that is `settings-audit`) for the failure modes that
+make a grant silently do nothing: interpreter-wildcard / blanket rules that Claude Code drops on
+entering auto mode, hardcoded absolute machine/user paths (Bash rules match literally, no expansion),
+and inert plugin self-grants. A deterministic detector scans skill/command/agent frontmatter
+`allowed-tools` and `settings.json` / `settings.local.json` `permissions.allow`, and recommends the
+bare-command-on-PATH pattern. The principle and citations live in the marketplace
+[permission-rule-hygiene convention](../../docs/conventions/permission-rule-hygiene/README.md).
+Report-only.
+
+```shell
+/claude-config-audit:permission-hygiene              # full grant audit
+/claude-config-audit:permission-hygiene frontmatter  # allowed-tools only
+/claude-config-audit:permission-hygiene settings     # permissions.allow only
+```
+
 ## Consumer conventions
 
 The skills read the consuming repo's own `CLAUDE.md` / `.claude/rules/` for project-specific policy:
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/SKILL.md b/plugins/claude-config-audit/skills/permission-hygiene/SKILL.md
new file mode 100644
index 000000000..e04a04610
--- /dev/null
+++ b/plugins/claude-config-audit/skills/permission-hygiene/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: permission-hygiene
+description: "Audit Claude Code permission GRANTS for portability and auto-mode durability — scans skill/command/agent frontmatter allowed-tools and settings.json/settings.local.json permissions.allow for interpreter-wildcard rules dropped in auto mode, hardcoded machine/user paths, and inert plugin self-grants. Use when: 'check permission rules', 'why was my allowed-tools grant ignored', 'audit allow rules', 'is this permission portable', after authoring a code-execution grant, or when a guarded helper is denied despite an allow rule. Report-only."
+argument-hint: "[scope] — scope: frontmatter|settings|plugins|all (default: all)"
+user-invocable: true
+disable-model-invocation: false
+---
+
+## Purpose
+
+Audit whether a repo's permission **grants** actually take effect. Answers a question the sibling
+`settings-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 convention:
+[docs/conventions/permission-rule-hygiene](../../../../docs/conventions/permission-rule-hygiene/README.md).
+The mechanical check definitions (P1/P2/P3, severities, detector invocation) are in
+[reference/criteria.md](reference/criteria.md).
+
+## 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, deprecated `:*` syntax, overly broad
+patterns, or live plugin drift belong to the sibling `settings-audit` skill. When a request is about
+those, route it there rather than answering here. `memory-health` owns the instruction layer
+(CLAUDE.md / rules / auto-memory).
+
+## Arguments
+
+Parse `$ARGUMENTS` for an optional scope filter:
+
+- `frontmatter` — skill/command/agent `allowed-tools` only
+- `settings` — `.claude/settings.json` + `.claude/settings.local.json` `permissions.allow` only
+- `plugins` — plugin `settings.json` self-grant (P3) only
+- `all` — everything (default)
+
+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/permission-hygiene/scripts/permission-rule-check.sh"
+```
+
+It scans frontmatter `allowed-tools` and settings `permissions.allow` across the consuming repo and
+prints one finding per fragile grant (`<severity> [<check>] <source>: <detail>`). `--count` prints the
+count. It requires `jq`; a missing `jq` exits 2 (report the environment gap rather than a clean bill).
+`settings.local.json` is parsed for its `permissions.allow` array only — never echoed wholesale.
+
+If a scope filter was given, run the full detector and present only the matching checks (P1/P2 map to
+`frontmatter`/`settings` sources; P3 to `plugins`).
+
+## 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: replace the fragile grant with the bare-name-on-PATH pattern from the
+convention, and add an **Operator setup** note where 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) |
+| warning | Interpreter/runner-led grant whose broad forms auto mode drops, or an inert self-grant (P1, P3) |
+
+A clean scan ("No fragile permission grants found.") is a valid outcome — report it as such.
+
+## Consumer conventions
+
+A consuming repo may declare, in its own `CLAUDE.md` / `.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.
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json b/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
new file mode 100644
index 000000000..5164e186e
--- /dev/null
+++ b/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
@@ -0,0 +1,65 @@
+{
+  "skill_name": "permission-hygiene",
+  "evals": [
+    {
+      "id": 1,
+      "name": "detect-happy-path",
+      "prompt": "Audit my Claude Code permission grants — are my allowed-tools and allow rules going to actually work?",
+      "expected_output": "Runs the deterministic detector over frontmatter allowed-tools and settings.json/settings.local.json permissions.allow, reporting per-finding severity for P1 (interpreter/runner-led grants whose broad forms auto mode drops), P2 (hardcoded machine/user paths), and P3 (inert plugin self-grants), and recommends the bare-name-on-PATH pattern.",
+      "files": [],
+      "expectations": [
+        "Output runs the permission-rule-check.sh detector rather than eyeballing rules",
+        "Output classifies findings as P1 (interpreter/runner-led), P2 (hardcoded path), and/or P3 (plugin self-grant)",
+        "Output recommends exposing a bare command on PATH and allowing the bare name narrowly"
+      ]
+    },
+    {
+      "id": 2,
+      "name": "scope-boundary-routes-out",
+      "prompt": "While auditing my permission grants, also check my baseline deny rules are present, flag any deprecated :* syntax, and check my plugins for upstream drift.",
+      "expected_output": "Audits only grant portability + auto-mode durability (P1/P2/P3) and routes baseline deny/ask presence, deprecated :* syntax, overly broad patterns, and plugin drift to the sibling settings-audit skill rather than handling them here.",
+      "files": [],
+      "expectations": [
+        "Output audits only the grant-hygiene question it owns (P1/P2/P3)",
+        "Output does NOT itself check baseline deny presence, deprecated :* syntax, or plugin drift",
+        "Output routes those to the settings-audit skill"
+      ]
+    },
+    {
+      "id": 3,
+      "name": "narrow-rule-not-flagged",
+      "prompt": "Is my allow rule Bash(npm test) a problem? What about Bash(babysit_merge.sh:*)?",
+      "expected_output": "Explains that narrow rules such as Bash(npm test) and a bare-name rule like Bash(babysit_merge.sh:*) carry over into auto mode and are NOT flagged — they are the correct shape — distinguishing them from the interpreter-wildcard grants that get dropped.",
+      "files": [],
+      "expectations": [
+        "Output states that narrow rules like Bash(npm test) carry over into auto mode and are not flagged",
+        "Output identifies Bash(babysit_merge.sh:*) as the correct bare-name pattern, not a finding",
+        "Output contrasts these with interpreter-wildcard rules that auto mode drops"
+      ]
+    },
+    {
+      "id": 4,
+      "name": "operator-setup-boundary",
+      "prompt": "My skill ships allowed-tools: ['Bash(python \"*merge.py\":*)'] so it can run its merge helper without prompts, but the helper still gets denied in auto mode. Fix it for me by editing the plugin so it grants itself the permission.",
+      "expected_output": "Explains the grant is dropped in auto mode (P1) and that a plugin/skill cannot self-grant this action class — a plugin settings.json supports only agent/subagentStatusLine, and self-modifying settings is blocked. Recommends exposing the helper as a bare command on PATH and having the operator add the bare-name rule to user-global ~/.claude/settings.json; does not claim to grant it from the plugin.",
+      "files": [],
+      "expectations": [
+        "Output explains the interpreter-wildcard grant is dropped when the session enters auto mode",
+        "Output explains a skill/plugin cannot self-grant this action class and the operative rule must go in user-global ~/.claude/settings.json",
+        "Output recommends the bare-command-on-PATH pattern with an operator-setup note rather than editing the plugin to self-grant"
+      ]
+    },
+    {
+      "id": 5,
+      "name": "report-only-no-fix",
+      "prompt": "Just auto-fix every fragile permission rule in my repo right now.",
+      "expected_output": "The skill is report-only. It runs the audit and presents findings with recommendations, but does not silently rewrite allow rules or write to user-global settings — P1/P2 rewrites are operator-confirmed judgment calls and the operative rule cannot be written by the skill.",
+      "files": [],
+      "expectations": [
+        "Output does not silently rewrite permission rules or write to ~/.claude/settings.json",
+        "Output produces the audit and per-finding recommendations instead",
+        "Output notes the operative rule and rule rewrites are operator actions"
+      ]
+    }
+  ]
+}
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md b/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
new file mode 100644
index 000000000..2f8f6ccb6
--- /dev/null
+++ b/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
@@ -0,0 +1,96 @@
+# Permission Hygiene Criteria
+
+Version: 1.0.0
+Last updated: 2026-07-14
+
+This file defines the checks the `permission-hygiene` audit runs. The **principle, the three
+anti-patterns, and the prescribed correct pattern — with official-doc citations — live in the
+marketplace convention** and are not restated here:
+[docs/conventions/permission-rule-hygiene](../../../../../docs/conventions/permission-rule-hygiene/README.md).
+This file is the mechanical check layer: what the detector flags, at what severity, and how to read a
+finding.
+
+The deterministic spine is
+`bash "${CLAUDE_PLUGIN_ROOT}/skills/permission-hygiene/scripts/permission-rule-check.sh"` — it scans
+skill/command/agent frontmatter `allowed-tools` and the `permissions.allow` arrays of
+`.claude/settings.json` and `.claude/settings.local.json`, plus any plugin `settings.json`, and emits
+one finding per fragile grant. It is advisory (always exits 0); `--count` prints the finding count.
+`settings.local.json` is parsed for its `permissions.allow` array only — never read or echoed wholesale
+(it may hold tokens).
+
+Findings are printed as `<severity> [<check>] <source>: <detail>`.
+
+---
+
+## P1: Interpreter-wildcard / blanket allow rule [warning]
+
+**What**: An `allowed-tools` or `permissions.allow` entry matching an action class Claude Code drops on
+entering auto mode — blanket `Bash(*)` / `PowerShell(*)` / bare `Bash` / bare `PowerShell`, a
+wildcarded interpreter (`Bash(python*)`, `Bash(node *)`, `Bash(bash <path>*)`, `Bash(sh -c*)`), a
+package-manager runner (`Bash(npx *)`, `Bash(uvx *)`, `Bash(pipx run *)`, `Bash(pnpm dlx *)`, …), or a
+script-glob command (`Bash(*.py:*)`).
+
+**How to check**: run the detector. Each P1 alternative requires a wildcard, so an exact narrow rule
+(`Bash(npm test)`, `Bash(cargo build)`, `Bash(babysit_merge.sh:*)`) is not flagged — matching the
+official "narrow rules carry over" behavior.
+
+**Why**: every P1 shape is interpreter/runner-led rather than the portable bare-name pattern, and the
+**broad forms** — blanket rules, package-manager runners, and interpreters with a wildcarded or
+globbed script target (e.g. `Bash(python "*helper.py":*)`) — are the ones auto mode drops, after which
+the grant does nothing and the action falls to the classifier. A grant that invokes one fixed script
+via an interpreter (`Bash(bash <fixed-path>:*)`) is flagged as the same authoring anti-pattern even
+where the doc's dropped-category wording does not clearly reach it; the fix (a bare PATH command) is
+the same. See convention anti-pattern 1.
+
+**Recommend**: expose the helper as a bare command on PATH and allow the bare name narrowly.
+
+## P2: Hardcoded absolute machine/user path [error]
+
+**What**: An entry containing a concrete user-home absolute path — `/c/Users/<name>/…` (POSIX-normalized
+Windows), `/home/<name>/…`, `/Users/<name>/…`, or `C:\Users\<name>\…`.
+
+**How to check**: run the detector. `${CLAUDE_PROJECT_DIR}/…`, `~/…`, and `//…` forms are not flagged
+(they expand or are portable anchors); only concrete usernames match.
+
+**Why**: Bash rules match literally with no `~`/`$HOME`/env expansion, so the rule breaks on other
+machines/usernames and leaks a username into version control. See convention anti-pattern 2.
+
+**Recommend**: replace with a machine-independent bare-name rule.
+
+## P3: Plugin self-granted permissions [warning]
+
+**What**: A plugin `settings.json` (a `settings.json` beside a `.claude-plugin/plugin.json`) that
+declares a `permissions` block.
+
+**How to check**: run the detector; it reports the offending plugin `settings.json`.
+
+**Why**: a plugin `settings.json` supports only the `agent` and `subagentStatusLine` keys, so a
+self-granted permission rule is inert; the operative rule must be added by the operator to
+`~/.claude/settings.json`. See convention anti-pattern 3.
+
+**Recommend**: remove the inert block; document an operator-setup note for the bare-name rule instead.
+
+---
+
+## Related but out of scope (route elsewhere)
+
+The sibling `settings-audit` skill owns config-**file correctness**: baseline deny/ask presence,
+deprecated `:*` syntax, overly broad patterns like `Bash(git *)`, and live plugin drift. This skill
+owns a different question — grant **portability and auto-mode durability**, and who adds the operative
+rule. When a request is about baseline security patterns, deprecated syntax, or drift, route it to
+`settings-audit` rather than answering here.
+
+## Output format
+
+```text
+## Permission Hygiene Report — {date}
+
+### Summary
+- Grants scanned: frontmatter allowed-tools + settings.json/settings.local.json permissions.allow
+- error: X findings (P2)
+- warning: X findings (P1, P3)
+
+### Findings
+| # | Check | Severity | Source | Finding | Recommended |
+|---|-------|----------|--------|---------|-------------|
+```
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
new file mode 100755
index 000000000..6dbff2107
--- /dev/null
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -0,0 +1,202 @@
+#!/usr/bin/env bash
+# permission-rule-check.sh — deterministic detector for fragile Claude Code
+# permission grants across a repo's skill/command/agent frontmatter and its
+# settings.json / settings.local.json permission rules.
+#
+# Flags three anti-patterns (criteria file: reference/criteria.md):
+#   P1  interpreter-wildcard / blanket allow rules that Claude Code DROPS on
+#       entering auto mode (blanket Bash(*)/PowerShell(*), wildcarded
+#       interpreters like Bash(python*), package-manager run wildcards,
+#       script-glob interpreters like Bash(*.py:*)). Narrow rules such as
+#       Bash(npm test) carry over and are NOT flagged.
+#   P2  hardcoded absolute user/machine home paths inside a rule. Bash rules
+#       match the command string literally — no ~, $HOME, or env expansion — so
+#       an absolute path breaks on other machines/usernames and leaks a
+#       username into version control.
+#   P3  a plugin settings.json that declares a `permissions` block. A plugin's
+#       settings.json supports only the `agent` and `subagentStatusLine` keys,
+#       so a self-granted permission rule is silently ignored; the operative
+#       allow-rule has to be added by the operator to ~/.claude/settings.json.
+#
+# Advisory: prints findings, ALWAYS exits 0 (findings never fail the run).
+# Requires jq for the settings-file half; exits 2 when jq is absent.
+#
+# Root resolution: $PERMISSION_HYGIENE_FIXTURE_DIR, else the cwd's git
+# toplevel, else $CLAUDE_PROJECT_DIR, else $PWD. Never the plugin's own dir.
+#
+# Usage:
+#   permission-rule-check.sh            # human-readable findings, one per line
+#   permission-rule-check.sh --count    # integer finding count only
+#   permission-rule-check.sh --help
+
+set -uo pipefail
+
+usage() {
+  cat <<'EOF'
+permission-rule-check.sh — flag fragile Claude Code permission grants.
+
+Usage: permission-rule-check.sh [--count|--help]
+
+  (no arg)   print one finding line per fragile grant; exit 0
+  --count    print the integer finding count only; exit 0
+  --help     this message
+
+Scans skill/command/agent frontmatter `allowed-tools` and the `permissions.allow`
+arrays of .claude/settings.json and .claude/settings.local.json for P1 (auto-mode
+-dropped interpreter/blanket rules), P2 (hardcoded machine paths), and plugin
+settings.json for P3 (unsupported self-granted `permissions`). Advisory — exit 0.
+Requires jq (exit 2 when absent).
+EOF
+}
+
+case "${1:-}" in
+  -h | --help)
+    usage
+    exit 0
+    ;;
+  *) ;;
+esac
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "ERROR: jq required" >&2
+  exit 2
+fi
+
+mode="report"
+[[ "${1:-}" == "--count" ]] && mode="count"
+
+if [[ -n "${PERMISSION_HYGIENE_FIXTURE_DIR:-}" ]]; then
+  ROOT="$PERMISSION_HYGIENE_FIXTURE_DIR"
+else
+  ROOT="$(git rev-parse --show-toplevel 2>/dev/null | tr -d '\r')"
+  [[ -n "$ROOT" ]] || ROOT="${CLAUDE_PROJECT_DIR:-$PWD}"
+fi
+
+# --- Detection patterns -------------------------------------------------------
+#
+# P1 — one ERE, case-sensitive on the tool name. Each alternative requires a
+# wildcard so an exact narrow rule (Bash(npm test)) never matches:
+#   1. blanket Bash(*) / PowerShell(*)
+#   2. an interpreter at the command position followed (eventually) by a *
+#   3. a package-manager run/exec command followed by a *
+#   4. a leading-glob command that resolves to a script (Bash(*.py:*))
+_interp='python3?|node|deno|bun|ruby|perl|php|bash|sh|zsh|pwsh|osascript|Rscript'
+_runner='npx|bunx|uvx|pnpm dlx|yarn dlx|pipx run|uv run|npm run|pnpm run|yarn run'
+_script='py|sh|rb|js|ts|mjs|cjs|pl|php'
+# Each alternative captures the whole Tool(...) spec (trailing [^)]*\) ) so a
+# finding reports the full offending rule, not a substring truncated at the *.
+P1_ERE="(Bash|PowerShell)\\(\\*\\)"
+P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*(${_interp})([^A-Za-z0-9_)][^)]*)?\\*[^)]*\\)"
+P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*(${_runner})([^A-Za-z0-9_)][^)]*)?\\*[^)]*\\)"
+P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*\\*[^)]*\\.(${_script})[^)]*\\)"
+
+# P2 — machine home-path shapes, ASSEMBLED FROM FRAGMENTS so no contiguous
+# path literal (e.g. the /Users/ or /home/ shape) appears in this file's source
+# bytes and trips the repo's own machine-specific-path scanner. `seg` is one
+# real segment character: not a separator, wildcard, or a placeholder/expansion
+# lead (<, $, {, ~), so `${CLAUDE_PROJECT_DIR}/…`, `~/…`, and doc placeholders
+# like `<name>` are not matched — only concrete usernames are.
+_sl='/'
+# shellcheck disable=SC1003  # _bs is a literal single backslash, not an escape
+_bs='\'
+_seg="[^${_sl}${_bs}*<>\${}~ ]"
+P2_ERE="${_sl}Users${_sl}${_seg}"                                    # macOS + POSIX-normalized Windows (/c/Users/…)
+P2_ERE="${P2_ERE}|${_sl}home${_sl}${_seg}"                           # Linux
+P2_ERE="${P2_ERE}|[A-Za-z]:[${_sl}${_bs}]Users[${_sl}${_bs}]${_seg}" # raw Windows drive
+
+findings=()
+
+emit() {
+  # emit <severity> <check> <source> <detail>
+  findings+=("$1 [$2] $3: $4")
+}
+
+scan_rule() {
+  # scan_rule <rule-string> <source-label> — one allow rule or one frontmatter token region
+  local text="$1" src="$2" m
+  while IFS= read -r m; do
+    [[ -n "$m" ]] && emit warning P1 "$src" "'$m' is an interpreter/runner-led grant, not the portable bare-name pattern; Claude Code drops the broad forms of this shape (blanket, package-manager runners, and wildcarded/globbed-target interpreters) on entering auto mode. Expose the guarded script as a bare PATH command and allow that, e.g. Bash(babysit_merge.sh:*)."
+  done < <(printf '%s\n' "$text" | grep -oE "$P1_ERE" 2>/dev/null | sort -u)
+  while IFS= read -r m; do
+    [[ -n "$m" ]] && emit error P2 "$src" "hardcoded machine path in '$m' — Bash rules match literally (no ~/\$HOME/env expansion), so this breaks on other machines/usernames and leaks a username into source control. Use a machine-independent bare-name rule."
+  done < <(printf '%s\n' "$text" | grep -oE "$P2_ERE" 2>/dev/null | sort -u)
+}
+
+# --- Frontmatter allowed-tools scan ------------------------------------------
+# allowed-tools value + its block-list continuation lines, from the leading
+# --- frontmatter block only.
+extract_allowed_tools() {
+  awk '
+    NR==1 && $0 !~ /^---[[:space:]]*$/ { exit }
+    NR==1 { infm=1; next }
+    infm && /^---[[:space:]]*$/ { exit }
+    infm {
+      if (cap) {
+        if ($0 ~ /^[[:space:]]/ || $0 ~ /^[[:space:]]*-/) { print; next }
+        else { cap=0 }
+      }
+      if ($0 ~ /^allowed-tools:[[:space:]]*/) { sub(/^allowed-tools:/, ""); print; cap=1 }
+    }
+  ' "$1" | tr -d '\r'
+}
+
+# SKILL.md anywhere, plus markdown directly under an agents/ or commands/ dir.
+while IFS= read -r file; do
+  [[ -f "$file" ]] || continue
+  at="$(extract_allowed_tools "$file")"
+  [[ -n "${at//[[:space:]]/}" ]] || continue
+  rel="${file#"$ROOT"/}"
+  scan_rule "$at" "$rel allowed-tools"
+done < <(
+  find "$ROOT" -type f \( \
+    -name 'SKILL.md' \
+    -o \( -name '*.md' -path '*/agents/*' \) \
+    -o \( -name '*.md' -path '*/commands/*' \) \
+    \) 2>/dev/null | sort -u
+)
+
+# --- Settings permissions.allow scan -----------------------------------------
+scan_settings_allow() {
+  local file="$1" label="$2" rule
+  [[ -f "$file" ]] || return 0
+  tr -d '\r' <"$file" | jq -e . >/dev/null 2>&1 || return 0
+  while IFS= read -r rule; do
+    [[ -n "$rule" ]] || continue
+    if [[ "$rule" == "Bash" || "$rule" == "PowerShell" ]]; then
+      emit warning P1 "$label" "bare '$rule' allow rule grants the whole tool and is dropped in auto mode. Allow a specific bare-name command instead, e.g. Bash(babysit_merge.sh:*)."
+    fi
+    scan_rule "$rule" "$label"
+    # Trailing tr strips CR: jq emits CRLF on Windows, which would otherwise
+    # leave a \r on each rule and defeat the exact bare-tool comparison above.
+  done < <(tr -d '\r' <"$file" | jq -r '.permissions.allow // [] | .[]' 2>/dev/null | tr -d '\r')
+}
+
+scan_settings_allow "$ROOT/.claude/settings.json" ".claude/settings.json permissions.allow"
+scan_settings_allow "$ROOT/.claude/settings.local.json" ".claude/settings.local.json permissions.allow"
+
+# --- Plugin self-grant scan (P3) ---------------------------------------------
+# A settings.json sitting at a plugin root (sibling .claude-plugin/plugin.json)
+# may only carry `agent` / `subagentStatusLine`; a `permissions` block is inert.
+while IFS= read -r manifest; do
+  plugin_dir="$(dirname "$(dirname "$manifest")")"
+  settings="$plugin_dir/settings.json"
+  [[ -f "$settings" ]] || continue
+  tr -d '\r' <"$settings" | jq -e . >/dev/null 2>&1 || continue
+  if tr -d '\r' <"$settings" | jq -e 'has("permissions")' >/dev/null 2>&1; then
+    rel="${settings#"$ROOT"/}"
+    emit warning P3 "$rel" "plugin settings.json declares 'permissions' — a plugin's settings.json supports only the agent and subagentStatusLine keys, so this grant is ignored. The operative allow-rule must be added by the operator to ~/.claude/settings.json."
+  fi
+done < <(find "$ROOT" -type f -path '*/.claude-plugin/plugin.json' 2>/dev/null | sort -u)
+
+# --- Output -------------------------------------------------------------------
+if [[ "$mode" == "count" ]]; then
+  printf '%s\n' "${#findings[@]}"
+  exit 0
+fi
+
+if [[ "${#findings[@]}" -eq 0 ]]; then
+  echo "No fragile permission grants found."
+else
+  printf '%s\n' "${findings[@]}"
+fi
+exit 0
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
new file mode 100755
index 000000000..7bbf45ff1
--- /dev/null
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -0,0 +1,179 @@
+#!/usr/bin/env bash
+# Regression tests for permission-rule-check.sh (self-contained — ships with the plugin).
+#
+# Machine-path fixtures are assembled at runtime from separator + segment
+# fragments so no contiguous machine-path literal appears in this file's source
+# bytes — the repo's own machine-specific-path scanner sees a clean test file.
+set -uo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SCRIPT="$SCRIPT_DIR/permission-rule-check.sh"
+
+TEST_TMPDIR="$(mktemp -d)"
+trap 'rm -rf "$TEST_TMPDIR"' EXIT
+
+FAILED=0
+CASE_NUM=0
+
+pass() {
+  CASE_NUM=$((CASE_NUM + 1))
+  printf 'PASS: %s\n' "$1"
+}
+fail() {
+  CASE_NUM=$((CASE_NUM + 1))
+  FAILED=$((FAILED + 1))
+  printf 'FAIL: %s\n  detail: %s\n' "$1" "$2" >&2
+}
+assert_eq() {
+  if [[ "$2" == "$3" ]]; then pass "$1"; else fail "$1" "expected: $2, actual: $3"; fi
+}
+assert_exit() {
+  if [[ "$2" == "$3" ]]; then pass "$1"; else fail "$1" "expected exit $2, got $3"; fi
+}
+assert_contains() {
+  case "$2" in
+    *"$3"*) pass "$1" ;;
+    *) fail "$1" "expected to contain: $3" ;;
+  esac
+}
+assert_not_contains() {
+  case "$2" in
+    *"$3"*) fail "$1" "unexpected substring: $3" ;;
+    *) pass "$1" ;;
+  esac
+}
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "SKIP: jq not installed" >&2
+  exit 0
+fi
+
+run() { PERMISSION_HYGIENE_FIXTURE_DIR="$1" bash "$SCRIPT" "${2:-}"; }
+
+# Runtime-assembled machine paths (no contiguous path literal in source).
+SL='/'
+# shellcheck disable=SC1003  # BS is a literal single backslash, not a quote escape
+BS='\'
+POSIX_MP="${SL}c${SL}Users${SL}alice${SL}.agents${SL}skills${SL}merge${SL}x.sh"
+WIN_MP="C:${BS}Users${BS}bob${BS}x.sh"
+
+# --- Case 1: --help ----------------------------------------------------------
+rc=0
+OUT=$(bash "$SCRIPT" --help) || rc=$?
+assert_exit "--help exits 0" 0 "$rc"
+assert_contains "--help prints usage" "$OUT" "Usage:"
+
+# --- Case 2: P1 interpreter/blanket rules in settings.allow ------------------
+D2="$TEST_TMPDIR/p1"
+mkdir -p "$D2/.claude"
+jq -n '{permissions:{allow:[
+  "Bash(*)","PowerShell(*)","Bash(python*)","Bash(node *)","Bash(sh -c*)",
+  "Bash(npx *)","Bash(*.py:*)","Bash"
+]}}' >"$D2/.claude/settings.json"
+rc=0
+OUT=$(run "$D2") || rc=$?
+assert_exit "P1 run exits 0 (advisory)" 0 "$rc"
+assert_contains "flags blanket Bash(*)" "$OUT" "Bash(*)"
+assert_contains "flags wildcarded interpreter python*" "$OUT" "Bash(python*)"
+assert_contains "flags interpreter node *" "$OUT" "Bash(node *)"
+assert_contains "flags sh -c*" "$OUT" "Bash(sh -c*)"
+assert_contains "flags package-manager runner npx *" "$OUT" "Bash(npx *)"
+assert_contains "flags script-glob interpreter *.py:*" "$OUT" "Bash(*.py:*)"
+assert_contains "flags PowerShell(*)" "$OUT" "PowerShell(*)"
+assert_contains "flags bare Bash allow" "$OUT" "bare 'Bash'"
+assert_contains "P1 findings tagged" "$OUT" "[P1]"
+
+# --- Case 3: narrow rules carry over — NOT flagged --------------------------
+D3="$TEST_TMPDIR/narrow"
+mkdir -p "$D3/.claude"
+jq -n '{permissions:{allow:[
+  "Bash(npm test)","Bash(cargo build)","Bash(git commit *)",
+  "Bash(babysit_merge.sh:*)","Read(~/.config/app/config.toml)"
+]}}' >"$D3/.claude/settings.json"
+OUT=$(run "$D3")
+assert_contains "clean narrow ruleset reports none" "$OUT" "No fragile permission grants"
+assert_eq "narrow ruleset count == 0" "0" "$(run "$D3" --count)"
+
+# --- Case 4: P2 hardcoded machine paths -------------------------------------
+D4="$TEST_TMPDIR/p2"
+mkdir -p "$D4/.claude"
+jq -n --arg posix "Bash(${POSIX_MP}:*)" --arg win "Bash(${WIN_MP}:*)" \
+  '{permissions:{allow:[$posix,$win]}}' >"$D4/.claude/settings.json"
+OUT=$(run "$D4")
+assert_contains "flags POSIX-normalized machine path" "$OUT" "[P2]"
+assert_contains "P2 detail mentions literal matching" "$OUT" "no ~/\$HOME"
+assert_eq "two machine-path findings" "2" "$(run "$D4" --count)"
+
+# --- Case 5: P2 exemptions — PROJECT_DIR / home-relative not flagged ---------
+D5="$TEST_TMPDIR/p2-exempt"
+mkdir -p "$D5/.claude"
+jq -n '{permissions:{allow:[
+  "Bash(${CLAUDE_PROJECT_DIR}/scripts/lint.sh *)","Read(~/Documents/notes.md)"
+]}}' >"$D5/.claude/settings.json"
+assert_eq "portable path forms not flagged" "0" "$(run "$D5" --count)"
+
+# --- Case 6: frontmatter allowed-tools (inline + block list) ----------------
+D6="$TEST_TMPDIR/frontmatter"
+mkdir -p "$D6/.claude/skills/bad" "$D6/.claude/skills/good" "$D6/.claude/agents"
+cat >"$D6/.claude/skills/bad/SKILL.md" <<'EOF'
+---
+name: bad
+allowed-tools: Bash(python "*merge.py":*)
+---
+body
+EOF
+cat >"$D6/.claude/skills/good/SKILL.md" <<'EOF'
+---
+name: good
+allowed-tools:
+  - Bash(git add *)
+  - Bash(npm test)
+---
+body
+EOF
+cat >"$D6/.claude/agents/runner.md" <<'EOF'
+---
+name: runner
+allowed-tools:
+  - Bash(node *)
+---
+body
+EOF
+OUT=$(run "$D6")
+assert_contains "flags interpreter in skill frontmatter" "$OUT" "skills/bad/SKILL.md allowed-tools"
+assert_contains "flags interpreter in agent frontmatter" "$OUT" "agents/runner.md allowed-tools"
+assert_not_contains "does NOT flag narrow git/npm skill" "$OUT" "skills/good/SKILL.md"
+
+# --- Case 7: P3 plugin self-grant -------------------------------------------
+D7="$TEST_TMPDIR/p3"
+mkdir -p "$D7/plugins/foo/.claude-plugin" "$D7/plugins/ok/.claude-plugin"
+printf '{"name":"foo"}\n' >"$D7/plugins/foo/.claude-plugin/plugin.json"
+printf '{"name":"ok"}\n' >"$D7/plugins/ok/.claude-plugin/plugin.json"
+jq -n '{permissions:{allow:["Bash(x.sh:*)"]}}' >"$D7/plugins/foo/settings.json"
+jq -n '{agent:{model:"opus"}}' >"$D7/plugins/ok/settings.json"
+OUT=$(run "$D7")
+assert_contains "flags plugin settings.json with permissions" "$OUT" "[P3]"
+assert_contains "P3 names the offending plugin file" "$OUT" "plugins/foo/settings.json"
+assert_not_contains "does NOT flag agent-only plugin settings" "$OUT" "plugins/ok/settings.json"
+
+# --- Case 8: clean repo ------------------------------------------------------
+D8="$TEST_TMPDIR/clean"
+mkdir -p "$D8/.claude"
+jq -n '{permissions:{allow:["Bash(babysit_merge.sh:*)"]}}' >"$D8/.claude/settings.json"
+assert_contains "clean repo message" "$(run "$D8")" "No fragile permission grants"
+
+# --- Case 9: missing jq exits 2 ---------------------------------------------
+real_bash=$(command -v bash)
+empty_path_dir="$TEST_TMPDIR/empty-path"
+mkdir -p "$empty_path_dir"
+rc=0
+err_out=$(PATH="$empty_path_dir" "$real_bash" "$SCRIPT" 2>&1) || rc=$?
+assert_exit "exit 2 when jq missing" 2 "$rc"
+assert_contains "jq required message" "$err_out" "jq required"
+
+if [[ "$FAILED" -eq 0 ]]; then
+  printf '\nAll %d checks passed.\n' "$CASE_NUM"
+  exit 0
+fi
+printf '\n%d/%d checks failed.\n' "$FAILED" "$CASE_NUM" >&2
+exit 1

From bdb2b424c51a607b711f3304665a7b8c50b35faa Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 02:02:53 -0400
Subject: [PATCH 2/8] fix(claude-config-audit): flag bare frontmatter grants;
 clear hygiene gate

permission-rule-check now detects a bare Bash/PowerShell grant in skill/agent
frontmatter allowed-tools, not only in settings.allow. criteria.md P1 already
lists bare Bash/PowerShell, but the frontmatter path ran only the parenthesized
P1 ERE, so a bare `allowed-tools: Bash` was missed. A single scan_bare_tool
helper now serves both the frontmatter and settings.allow paths.

Also clears two hygiene checks introduced by this branch:
- typos: drop "invokable" from the plugins-reference quote (repo standard is
  "invocable"); the ellipsis keeps the abridged citation without a misquote.
- machine-specific-paths: reword the P2 comment so no contiguous home-path
  literal trips the repo's own scanner.
---
 .../permission-rule-hygiene/README.md         |  2 +-
 .../scripts/permission-rule-check.sh          | 26 ++++++++++++++-----
 .../scripts/permission-rule-check.test.sh     |  9 +++++++
 3 files changed, 30 insertions(+), 7 deletions(-)

diff --git a/docs/conventions/permission-rule-hygiene/README.md b/docs/conventions/permission-rule-hygiene/README.md
index ec36ebdcd..4052703d6 100644
--- a/docs/conventions/permission-rule-hygiene/README.md
+++ b/docs/conventions/permission-rule-hygiene/README.md
@@ -99,7 +99,7 @@ name narrowly:
    - Pre-plugin: a small PATH shim in a directory already on your PATH (e.g. `~/.local/bin`, if it is
      on your PATH) that delegates through `$HOME` to the skill's self-locating wrapper.
    - Post-migration: the plugin's `bin/` directory — "Executables added to the Bash tool's `PATH` …
-     invokable as bare commands in any Bash tool call while the plugin is enabled" —
+     as bare commands in any Bash tool call while the plugin is enabled" —
      [plugins-reference](https://code.claude.com/docs/en/plugins-reference) (Executables row).
    - Wrappers self-locate their real directory (e.g. `readlink -f`) so they work via direct, shim, or
      symlink invocation.
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
index 6dbff2107..3252238ea 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -91,8 +91,8 @@ P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*(${_runner})([^A-Za-z0-9_)][^)]*)?\
 P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*\\*[^)]*\\.(${_script})[^)]*\\)"
 
 # P2 — machine home-path shapes, ASSEMBLED FROM FRAGMENTS so no contiguous
-# path literal (e.g. the /Users/ or /home/ shape) appears in this file's source
-# bytes and trips the repo's own machine-specific-path scanner. `seg` is one
+# home-path literal appears in this file's source bytes and trips the repo's
+# own machine-specific-path scanner. `seg` is one
 # real segment character: not a separator, wildcard, or a placeholder/expansion
 # lead (<, $, {, ~), so `${CLAUDE_PROJECT_DIR}/…`, `~/…`, and doc placeholders
 # like `<name>` are not matched — only concrete usernames are.
@@ -122,6 +122,21 @@ scan_rule() {
   done < <(printf '%s\n' "$text" | grep -oE "$P2_ERE" 2>/dev/null | sort -u)
 }
 
+scan_bare_tool() {
+  # scan_bare_tool <text> <source-label> — flag a bare `Bash`/`PowerShell`
+  # token (the whole-tool grant that auto mode drops). scan_settings_allow
+  # exact-matches this per rule; frontmatter arrives as a blob the parenthesized
+  # P1 ERE cannot see, so it needs a token-level scan. A token immediately
+  # followed by `(` (e.g. Bash(npm test)) is a scoped rule, not a bare grant,
+  # and is excluded so an interpreter rule is not double-flagged.
+  local text="$1" src="$2" tool
+  for tool in Bash PowerShell; do
+    if printf '%s\n' "$text" | grep -qE "(^|[^[:alnum:]_])${tool}([^[:alnum:]_(]|\$)"; then
+      emit warning P1 "$src" "bare '$tool' allow rule grants the whole tool and is dropped in auto mode. Allow a specific bare-name command instead, e.g. Bash(babysit_merge.sh:*)."
+    fi
+  done
+}
+
 # --- Frontmatter allowed-tools scan ------------------------------------------
 # allowed-tools value + its block-list continuation lines, from the leading
 # --- frontmatter block only.
@@ -147,6 +162,7 @@ while IFS= read -r file; do
   [[ -n "${at//[[:space:]]/}" ]] || continue
   rel="${file#"$ROOT"/}"
   scan_rule "$at" "$rel allowed-tools"
+  scan_bare_tool "$at" "$rel allowed-tools"
 done < <(
   find "$ROOT" -type f \( \
     -name 'SKILL.md' \
@@ -162,12 +178,10 @@ scan_settings_allow() {
   tr -d '\r' <"$file" | jq -e . >/dev/null 2>&1 || return 0
   while IFS= read -r rule; do
     [[ -n "$rule" ]] || continue
-    if [[ "$rule" == "Bash" || "$rule" == "PowerShell" ]]; then
-      emit warning P1 "$label" "bare '$rule' allow rule grants the whole tool and is dropped in auto mode. Allow a specific bare-name command instead, e.g. Bash(babysit_merge.sh:*)."
-    fi
+    scan_bare_tool "$rule" "$label"
     scan_rule "$rule" "$label"
     # Trailing tr strips CR: jq emits CRLF on Windows, which would otherwise
-    # leave a \r on each rule and defeat the exact bare-tool comparison above.
+    # leave a \r on each rule and pollute the token the scans above match.
   done < <(tr -d '\r' <"$file" | jq -r '.permissions.allow // [] | .[]' 2>/dev/null | tr -d '\r')
 }
 
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
index 7bbf45ff1..bd75f4353 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -139,9 +139,18 @@ allowed-tools:
 ---
 body
 EOF
+mkdir -p "$D6/.claude/skills/bare"
+cat >"$D6/.claude/skills/bare/SKILL.md" <<'EOF'
+---
+name: bare
+allowed-tools: Bash
+---
+body
+EOF
 OUT=$(run "$D6")
 assert_contains "flags interpreter in skill frontmatter" "$OUT" "skills/bad/SKILL.md allowed-tools"
 assert_contains "flags interpreter in agent frontmatter" "$OUT" "agents/runner.md allowed-tools"
+assert_contains "flags bare Bash in skill frontmatter" "$OUT" "skills/bare/SKILL.md allowed-tools: bare 'Bash'"
 assert_not_contains "does NOT flag narrow git/npm skill" "$OUT" "skills/good/SKILL.md"
 
 # --- Case 7: P3 plugin self-grant -------------------------------------------

From eebecce449f3753960639d0883d2b1a41d94efce Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 02:31:07 -0400
Subject: [PATCH 3/8] feat(claude-config-audit): flag Agent allow rules as
 auto-mode-dropped
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

permission-rule-check now flags `Agent` and scoped `Agent(...)` allow rules in
permissions.allow and skill/agent frontmatter allowed-tools. Claude Code drops
all Agent allow rules on entering auto mode — like blanket/wildcarded
interpreters — but unlike a shell helper they have no bare-command-on-PATH
analog, so the finding recommends removing/re-scoping the rule or running
outside auto mode.

A dedicated scan_agent helper covers both surfaces; a scoped Agent(...) is not
a narrow carry-over (no other detector reaches it), so both bare and
parenthesized forms flag. Adds regression cases (settings + frontmatter, bare
and scoped) and an evals case; documents the shape in the convention and P1
criteria.
---
 .../permission-rule-hygiene/README.md         |  4 ++++
 .../permission-hygiene/evals/evals.json       | 12 ++++++++++
 .../permission-hygiene/reference/criteria.md  |  8 ++++---
 .../scripts/permission-rule-check.sh          | 20 ++++++++++++++--
 .../scripts/permission-rule-check.test.sh     | 24 ++++++++++++++++++-
 5 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/docs/conventions/permission-rule-hygiene/README.md b/docs/conventions/permission-rule-hygiene/README.md
index 4052703d6..ac848698b 100644
--- a/docs/conventions/permission-rule-hygiene/README.md
+++ b/docs/conventions/permission-rule-hygiene/README.md
@@ -50,6 +50,10 @@ runner (`npx`, `uvx`, `pipx run`, `pnpm dlx`, …), silently grants nothing unde
 then depends entirely on the classifier. Empirically, a guarded merge helper granted this way was
 denied even when invoked bare.
 
+`Agent` allow rules (both bare `Agent` and scoped `Agent(...)`) are dropped the same way, and are
+flagged too — but unlike a shell helper they have no bare-command-on-PATH analog to re-scope to.
+Remove or re-scope the rule, or run the sub-agent action outside auto mode.
+
 ## Anti-pattern 2 — hardcoded absolute machine/user paths
 
 Bash permission rules match the command string **literally**. Per
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json b/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
index 5164e186e..44e81c28a 100644
--- a/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
+++ b/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
@@ -60,6 +60,18 @@
         "Output produces the audit and per-finding recommendations instead",
         "Output notes the operative rule and rule rewrites are operator actions"
       ]
+    },
+    {
+      "id": 6,
+      "name": "agent-allow-rule-flagged",
+      "prompt": "I added \"Agent\" and \"Agent(code-reviewer)\" to permissions.allow so my sub-agent runs without prompts in auto mode. Are those grants going to work?",
+      "expected_output": "Flags both the bare Agent and scoped Agent(code-reviewer) allow rules as P1 — Claude Code drops all Agent allow rules on entering auto mode, categorically (there is no narrow Agent carry-over like Bash(npm test)). Notes that Agent has no bare-command-on-PATH analog to re-scope to, so the fix is to remove or re-scope the rule, or run the sub-agent action outside auto mode.",
+      "files": [],
+      "expectations": [
+        "Output flags both bare Agent and scoped Agent(...) allow rules as P1",
+        "Output explains Agent allow rules are dropped categorically in auto mode, with no narrow carry-over form",
+        "Output notes Agent has no bare-PATH analog and recommends removing/re-scoping the rule or running outside auto mode"
+      ]
     }
   ]
 }
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md b/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
index 2f8f6ccb6..6e5efc7ee 100644
--- a/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
+++ b/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
@@ -27,8 +27,9 @@ Findings are printed as `<severity> [<check>] <source>: <detail>`.
 **What**: An `allowed-tools` or `permissions.allow` entry matching an action class Claude Code drops on
 entering auto mode — blanket `Bash(*)` / `PowerShell(*)` / bare `Bash` / bare `PowerShell`, a
 wildcarded interpreter (`Bash(python*)`, `Bash(node *)`, `Bash(bash <path>*)`, `Bash(sh -c*)`), a
-package-manager runner (`Bash(npx *)`, `Bash(uvx *)`, `Bash(pipx run *)`, `Bash(pnpm dlx *)`, …), or a
-script-glob command (`Bash(*.py:*)`).
+package-manager runner (`Bash(npx *)`, `Bash(uvx *)`, `Bash(pipx run *)`, `Bash(pnpm dlx *)`, …), a
+script-glob command (`Bash(*.py:*)`), or an `Agent` allow rule (bare `Agent` or scoped `Agent(...)` —
+both dropped categorically, with no narrow carry-over form).
 
 **How to check**: run the detector. Each P1 alternative requires a wildcard, so an exact narrow rule
 (`Bash(npm test)`, `Bash(cargo build)`, `Bash(babysit_merge.sh:*)`) is not flagged — matching the
@@ -42,7 +43,8 @@ via an interpreter (`Bash(bash <fixed-path>:*)`) is flagged as the same authorin
 where the doc's dropped-category wording does not clearly reach it; the fix (a bare PATH command) is
 the same. See convention anti-pattern 1.
 
-**Recommend**: expose the helper as a bare command on PATH and allow the bare name narrowly.
+**Recommend**: expose the helper as a bare command on PATH and allow the bare name narrowly. An
+`Agent` rule has no bare-PATH analog — remove or re-scope it, or run outside auto mode.
 
 ## P2: Hardcoded absolute machine/user path [error]
 
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
index 3252238ea..a972ba6a6 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -7,8 +7,9 @@
 #   P1  interpreter-wildcard / blanket allow rules that Claude Code DROPS on
 #       entering auto mode (blanket Bash(*)/PowerShell(*), wildcarded
 #       interpreters like Bash(python*), package-manager run wildcards,
-#       script-glob interpreters like Bash(*.py:*)). Narrow rules such as
-#       Bash(npm test) carry over and are NOT flagged.
+#       script-glob interpreters like Bash(*.py:*), and Agent allow rules —
+#       both bare Agent and Agent(...), which auto mode drops categorically).
+#       Narrow rules such as Bash(npm test) carry over and are NOT flagged.
 #   P2  hardcoded absolute user/machine home paths inside a rule. Bash rules
 #       match the command string literally — no ~, $HOME, or env expansion — so
 #       an absolute path breaks on other machines/usernames and leaks a
@@ -137,6 +138,19 @@ scan_bare_tool() {
   done
 }
 
+scan_agent() {
+  # scan_agent <text> <source-label> — flag any `Agent` allow rule, whether bare
+  # `Agent` or scoped `Agent(...)`. Unlike Bash/PowerShell, a scoped Agent rule
+  # is NOT a narrow carry-over: auto mode drops all Agent allow rules
+  # categorically, and Agent has no bare-PATH-command analog to re-scope to. The
+  # trailing boundary is `[^[:alnum:]_]` (includes `(`) so the parenthesized form
+  # is caught too; the leading `_` exclusion keeps `mcp__x__Agent` from matching.
+  local text="$1" src="$2"
+  if printf '%s\n' "$text" | grep -qE "(^|[^[:alnum:]_])Agent([^[:alnum:]_]|\$)"; then
+    emit warning P1 "$src" "Agent allow rules are dropped in auto mode and have no PATH-durable analog — remove/re-scope, or run outside auto mode."
+  fi
+}
+
 # --- Frontmatter allowed-tools scan ------------------------------------------
 # allowed-tools value + its block-list continuation lines, from the leading
 # --- frontmatter block only.
@@ -163,6 +177,7 @@ while IFS= read -r file; do
   rel="${file#"$ROOT"/}"
   scan_rule "$at" "$rel allowed-tools"
   scan_bare_tool "$at" "$rel allowed-tools"
+  scan_agent "$at" "$rel allowed-tools"
 done < <(
   find "$ROOT" -type f \( \
     -name 'SKILL.md' \
@@ -179,6 +194,7 @@ scan_settings_allow() {
   while IFS= read -r rule; do
     [[ -n "$rule" ]] || continue
     scan_bare_tool "$rule" "$label"
+    scan_agent "$rule" "$label"
     scan_rule "$rule" "$label"
     # Trailing tr strips CR: jq emits CRLF on Windows, which would otherwise
     # leave a \r on each rule and pollute the token the scans above match.
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
index bd75f4353..99a06ca06 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -68,7 +68,7 @@ D2="$TEST_TMPDIR/p1"
 mkdir -p "$D2/.claude"
 jq -n '{permissions:{allow:[
   "Bash(*)","PowerShell(*)","Bash(python*)","Bash(node *)","Bash(sh -c*)",
-  "Bash(npx *)","Bash(*.py:*)","Bash"
+  "Bash(npx *)","Bash(*.py:*)","Bash","Agent","Agent(code-reviewer)"
 ]}}' >"$D2/.claude/settings.json"
 rc=0
 OUT=$(run "$D2") || rc=$?
@@ -81,8 +81,20 @@ assert_contains "flags package-manager runner npx *" "$OUT" "Bash(npx *)"
 assert_contains "flags script-glob interpreter *.py:*" "$OUT" "Bash(*.py:*)"
 assert_contains "flags PowerShell(*)" "$OUT" "PowerShell(*)"
 assert_contains "flags bare Bash allow" "$OUT" "bare 'Bash'"
+assert_contains "flags Agent allow rule" "$OUT" "Agent allow rules are dropped"
 assert_contains "P1 findings tagged" "$OUT" "[P1]"
 
+# --- Case 2b: scoped Agent(...) is flagged (no other detector covers it) -----
+# Unlike Bash(npm test), a scoped Agent rule is NOT a narrow carry-over: auto
+# mode drops all Agent allow rules, so the parenthesized form must flag too.
+D2B="$TEST_TMPDIR/agent-scoped"
+mkdir -p "$D2B/.claude"
+jq -n '{permissions:{allow:["Agent(code-reviewer)"]}}' >"$D2B/.claude/settings.json"
+OUT=$(run "$D2B")
+assert_contains "flags scoped Agent(code-reviewer)" "$OUT" "Agent allow rules are dropped"
+assert_contains "scoped Agent finding tagged P1" "$OUT" "[P1]"
+assert_eq "scoped Agent produces exactly one finding" "1" "$(run "$D2B" --count)"
+
 # --- Case 3: narrow rules carry over — NOT flagged --------------------------
 D3="$TEST_TMPDIR/narrow"
 mkdir -p "$D3/.claude"
@@ -147,10 +159,20 @@ allowed-tools: Bash
 ---
 body
 EOF
+mkdir -p "$D6/.claude/skills/agent"
+cat >"$D6/.claude/skills/agent/SKILL.md" <<'EOF'
+---
+name: agent
+allowed-tools:
+  - Agent(code-reviewer)
+---
+body
+EOF
 OUT=$(run "$D6")
 assert_contains "flags interpreter in skill frontmatter" "$OUT" "skills/bad/SKILL.md allowed-tools"
 assert_contains "flags interpreter in agent frontmatter" "$OUT" "agents/runner.md allowed-tools"
 assert_contains "flags bare Bash in skill frontmatter" "$OUT" "skills/bare/SKILL.md allowed-tools: bare 'Bash'"
+assert_contains "flags Agent rule in skill frontmatter" "$OUT" "skills/agent/SKILL.md allowed-tools: Agent allow rules are dropped"
 assert_not_contains "does NOT flag narrow git/npm skill" "$OUT" "skills/good/SKILL.md"
 
 # --- Case 7: P3 plugin self-grant -------------------------------------------

From 1c403c00e8bf5a2b4999b8e372f7a02e3bc8abf8 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 02:40:46 -0400
Subject: [PATCH 4/8] fix(claude-config-audit): anchor Agent match to the
 rule's own tool token
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

scan_agent scanned the whole rule string for the word `Agent`, so a valid shell
grant whose payload merely contains it — `Bash(echo Agent)`, `Bash(find
*Agent*)` — was falsely reported as an Agent allow rule. Split the text into
top-level `Tool` / `Tool(...)` tokens first (the greedy parenthesized group
swallows a tool's whole payload, so an inner `Agent` never surfaces as its own
token) and flag only a token that is `Agent` or begins `Agent(`.

Adds a regression case asserting `Agent` inside a Bash payload is not flagged.
---
 .../scripts/permission-rule-check.sh          | 24 ++++++++++++-------
 .../scripts/permission-rule-check.test.sh     |  4 +++-
 2 files changed, 19 insertions(+), 9 deletions(-)

diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
index a972ba6a6..c1a455439 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -139,16 +139,24 @@ scan_bare_tool() {
 }
 
 scan_agent() {
-  # scan_agent <text> <source-label> — flag any `Agent` allow rule, whether bare
+  # scan_agent <text> <source-label> — flag an `Agent` allow rule, whether bare
   # `Agent` or scoped `Agent(...)`. Unlike Bash/PowerShell, a scoped Agent rule
   # is NOT a narrow carry-over: auto mode drops all Agent allow rules
-  # categorically, and Agent has no bare-PATH-command analog to re-scope to. The
-  # trailing boundary is `[^[:alnum:]_]` (includes `(`) so the parenthesized form
-  # is caught too; the leading `_` exclusion keeps `mcp__x__Agent` from matching.
-  local text="$1" src="$2"
-  if printf '%s\n' "$text" | grep -qE "(^|[^[:alnum:]_])Agent([^[:alnum:]_]|\$)"; then
-    emit warning P1 "$src" "Agent allow rules are dropped in auto mode and have no PATH-durable analog — remove/re-scope, or run outside auto mode."
-  fi
+  # categorically, and Agent has no bare-PATH-command analog to re-scope to.
+  #
+  # The word "Agent" must be the rule's own tool token, not a fragment inside
+  # another tool's payload (e.g. Bash(echo Agent), Bash(find *Agent*)). So the
+  # text is first split into top-level `Tool` / `Tool(...)` tokens — the greedy
+  # `(\(...\))?` consumes a tool's whole parenthesized payload as one token, so
+  # an inner "Agent" never surfaces as its own token — then only a token that IS
+  # `Agent` or begins `Agent(` is flagged.
+  local text="$1" src="$2" tok
+  while IFS= read -r tok; do
+    if [[ "$tok" == "Agent" || "$tok" == "Agent("* ]]; then
+      emit warning P1 "$src" "Agent allow rules are dropped in auto mode and have no PATH-durable analog — remove/re-scope, or run outside auto mode."
+      break
+    fi
+  done < <(printf '%s\n' "$text" | grep -oE '[A-Za-z_][A-Za-z0-9_]*(\([^)]*\))?' 2>/dev/null)
 }
 
 # --- Frontmatter allowed-tools scan ------------------------------------------
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
index 99a06ca06..d1d4056ea 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -100,10 +100,12 @@ D3="$TEST_TMPDIR/narrow"
 mkdir -p "$D3/.claude"
 jq -n '{permissions:{allow:[
   "Bash(npm test)","Bash(cargo build)","Bash(git commit *)",
-  "Bash(babysit_merge.sh:*)","Read(~/.config/app/config.toml)"
+  "Bash(babysit_merge.sh:*)","Read(~/.config/app/config.toml)",
+  "Bash(echo Agent)","Bash(find *Agent*)"
 ]}}' >"$D3/.claude/settings.json"
 OUT=$(run "$D3")
 assert_contains "clean narrow ruleset reports none" "$OUT" "No fragile permission grants"
+assert_not_contains "word 'Agent' inside a Bash payload is not an Agent finding" "$OUT" "Agent allow rules are dropped"
 assert_eq "narrow ruleset count == 0" "0" "$(run "$D3" --count)"
 
 # --- Case 4: P2 hardcoded machine paths -------------------------------------

From 5b57cbb6badd662cce129a358a4752d68db99603 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 03:37:37 -0400
Subject: [PATCH 5/8] feat(claude-config-audit): flag bare package-manager
 wildcards; skip vendored skills
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two permission-hygiene detector refinements:

P1 now flags bare package-manager wildcard grants — Bash(npm:*), Bash(npm *),
Bash(pnpm:*), Bash(yarn:*). A bare package manager behind a wildcard permits
arbitrary execution (npm exec, npm run <anything>, lifecycle scripts), so it is
interpreter/runner-led rather than the durable bare-name pattern and auto mode
drops it. Folding npm|pnpm|yarn into the runner alternation subsumes the former
npm run|pnpm run|yarn run entries (a bare name matches its own run wildcard).
Fixed subcommands — Bash(npm test), Bash(npm run build) — carry no wildcard,
carry over into auto mode, and are not flagged.

The frontmatter scan now skips any SKILL.md/agent/command under a vendor/ path
segment. A vendored file is an upstream reference, not a loadable skill, so its
allowed-tools never take effect; flagging one (e.g. the playwright plugin's
vendored SKILL.md granting Bash(npx:*)/Bash(npm:*)) was a false positive.

Adds regression cases for both (flagged vs. carried-over package-manager forms;
real-vs-vendored SKILL.md), an evals case, and criteria/convention notes.
---
 .../permission-rule-hygiene/README.md         |  8 +++++
 .../permission-hygiene/evals/evals.json       | 12 +++++++
 .../permission-hygiene/reference/criteria.md  | 15 ++++++---
 .../scripts/permission-rule-check.sh          | 24 +++++++++++---
 .../scripts/permission-rule-check.test.sh     | 33 +++++++++++++++++--
 5 files changed, 80 insertions(+), 12 deletions(-)

diff --git a/docs/conventions/permission-rule-hygiene/README.md b/docs/conventions/permission-rule-hygiene/README.md
index ac848698b..eaeac45a5 100644
--- a/docs/conventions/permission-rule-hygiene/README.md
+++ b/docs/conventions/permission-rule-hygiene/README.md
@@ -50,6 +50,14 @@ runner (`npx`, `uvx`, `pipx run`, `pnpm dlx`, …), silently grants nothing unde
 then depends entirely on the classifier. Empirically, a guarded merge helper granted this way was
 denied even when invoked bare.
 
+A **bare package-manager wildcard** — `Bash(npm:*)`, `Bash(npm *)`, `Bash(pnpm:*)`, `Bash(yarn:*)` —
+is the same anti-pattern: it reads like a scoped grant but permits arbitrary execution (`npm exec`,
+`npm run <anything>`, lifecycle scripts), so it is interpreter/runner-led rather than the bare-name
+pattern and is flagged. The doc's dropped-category wording enumerates "package-manager run commands";
+this bare form is broader than — not narrower than — that category, so it is treated as the same
+authoring anti-pattern with the same fix. A **fixed** package-manager subcommand (`Bash(npm test)`,
+`Bash(npm run build)`) carries no wildcard, carries over into auto mode, and is not flagged.
+
 `Agent` allow rules (both bare `Agent` and scoped `Agent(...)`) are dropped the same way, and are
 flagged too — but unlike a shell helper they have no bare-command-on-PATH analog to re-scope to.
 Remove or re-scope the rule, or run the sub-agent action outside auto mode.
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json b/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
index 44e81c28a..472e98c6a 100644
--- a/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
+++ b/plugins/claude-config-audit/skills/permission-hygiene/evals/evals.json
@@ -72,6 +72,18 @@
         "Output explains Agent allow rules are dropped categorically in auto mode, with no narrow carry-over form",
         "Output notes Agent has no bare-PATH analog and recommends removing/re-scoping the rule or running outside auto mode"
       ]
+    },
+    {
+      "id": 7,
+      "name": "bare-package-manager-wildcard-flagged",
+      "prompt": "I added Bash(npm:*) and Bash(pnpm:*) to permissions.allow so my package-manager scripts run without prompts in auto mode, and Bash(npm test) for CI. Which of these actually hold up?",
+      "expected_output": "Flags Bash(npm:*) and Bash(pnpm:*) as P1 — a bare package-manager wildcard permits arbitrary execution (npm exec, npm run <anything>, lifecycle scripts), so it is interpreter/runner-led rather than the bare-name pattern and auto mode drops it. Explains that Bash(npm test) and Bash(npm run build) are fixed subcommands with no wildcard, carry over into auto mode, and are not flagged. Recommends exposing the guarded action as a bare command on PATH and allowing that narrowly.",
+      "files": [],
+      "expectations": [
+        "Output flags bare package-manager wildcards like Bash(npm:*) and Bash(pnpm:*) as P1",
+        "Output explains a bare package-manager wildcard permits arbitrary execution and is dropped in auto mode",
+        "Output states fixed subcommands like Bash(npm test) and Bash(npm run build) carry over into auto mode and are not flagged"
+      ]
     }
   ]
 }
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md b/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
index 6e5efc7ee..625ff3baa 100644
--- a/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
+++ b/plugins/claude-config-audit/skills/permission-hygiene/reference/criteria.md
@@ -14,7 +14,10 @@ The deterministic spine is
 `bash "${CLAUDE_PLUGIN_ROOT}/skills/permission-hygiene/scripts/permission-rule-check.sh"` — it scans
 skill/command/agent frontmatter `allowed-tools` and the `permissions.allow` arrays of
 `.claude/settings.json` and `.claude/settings.local.json`, plus any plugin `settings.json`, and emits
-one finding per fragile grant. It is advisory (always exits 0); `--count` prints the finding count.
+one finding per fragile grant. Frontmatter files under a `vendor/` path segment are skipped: they are
+vendored upstream references, not loadable skills/agents/commands, so their `allowed-tools` never take
+effect and a finding on them would be a false positive. It is advisory (always exits 0); `--count`
+prints the finding count.
 `settings.local.json` is parsed for its `permissions.allow` array only — never read or echoed wholesale
 (it may hold tokens).
 
@@ -27,13 +30,15 @@ Findings are printed as `<severity> [<check>] <source>: <detail>`.
 **What**: An `allowed-tools` or `permissions.allow` entry matching an action class Claude Code drops on
 entering auto mode — blanket `Bash(*)` / `PowerShell(*)` / bare `Bash` / bare `PowerShell`, a
 wildcarded interpreter (`Bash(python*)`, `Bash(node *)`, `Bash(bash <path>*)`, `Bash(sh -c*)`), a
-package-manager runner (`Bash(npx *)`, `Bash(uvx *)`, `Bash(pipx run *)`, `Bash(pnpm dlx *)`, …), a
-script-glob command (`Bash(*.py:*)`), or an `Agent` allow rule (bare `Agent` or scoped `Agent(...)` —
+package-manager grant — a runner subcommand (`Bash(npx *)`, `Bash(uvx *)`, `Bash(pipx run *)`,
+`Bash(pnpm dlx *)`, …) or a bare package-manager wildcard (`Bash(npm:*)`, `Bash(npm *)`,
+`Bash(pnpm:*)`, `Bash(yarn:*)`), which grants arbitrary execution via `npm exec` / lifecycle scripts —
+a script-glob command (`Bash(*.py:*)`), or an `Agent` allow rule (bare `Agent` or scoped `Agent(...)` —
 both dropped categorically, with no narrow carry-over form).
 
 **How to check**: run the detector. Each P1 alternative requires a wildcard, so an exact narrow rule
-(`Bash(npm test)`, `Bash(cargo build)`, `Bash(babysit_merge.sh:*)`) is not flagged — matching the
-official "narrow rules carry over" behavior.
+(`Bash(npm test)`, `Bash(npm run build)`, `Bash(cargo build)`, `Bash(babysit_merge.sh:*)`) is not
+flagged — matching the official "narrow rules carry over" behavior.
 
 **Why**: every P1 shape is interpreter/runner-led rather than the portable bare-name pattern, and the
 **broad forms** — blanket rules, package-manager runners, and interpreters with a wildcarded or
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
index c1a455439..e92334c0a 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -6,8 +6,10 @@
 # Flags three anti-patterns (criteria file: reference/criteria.md):
 #   P1  interpreter-wildcard / blanket allow rules that Claude Code DROPS on
 #       entering auto mode (blanket Bash(*)/PowerShell(*), wildcarded
-#       interpreters like Bash(python*), package-manager run wildcards,
-#       script-glob interpreters like Bash(*.py:*), and Agent allow rules —
+#       interpreters like Bash(python*), package-manager wildcards — runner
+#       subcommands (Bash(npx *)) and bare package managers (Bash(npm:*),
+#       Bash(npm *)) — script-glob interpreters like Bash(*.py:*), and Agent
+#       allow rules —
 #       both bare Agent and Agent(...), which auto mode drops categorically).
 #       Narrow rules such as Bash(npm test) carry over and are NOT flagged.
 #   P2  hardcoded absolute user/machine home paths inside a rule. Bash rules
@@ -79,10 +81,16 @@ fi
 # wildcard so an exact narrow rule (Bash(npm test)) never matches:
 #   1. blanket Bash(*) / PowerShell(*)
 #   2. an interpreter at the command position followed (eventually) by a *
-#   3. a package-manager run/exec command followed by a *
+#   3. a package-manager run/exec command followed by a * — both the run/exec
+#      subcommand forms (npx, pnpm dlx, uv run, …) and a bare package manager
+#      wildcard (Bash(npm:*), Bash(npm *)), which grants arbitrary execution
+#      via npm exec / lifecycle scripts. A bare package-manager name subsumes
+#      its own run wildcard (npm matches `npm run *`), so `npm run` etc. are not
+#      listed separately. A fixed subcommand (Bash(npm test), Bash(npm run
+#      build)) carries no * and is not matched.
 #   4. a leading-glob command that resolves to a script (Bash(*.py:*))
 _interp='python3?|node|deno|bun|ruby|perl|php|bash|sh|zsh|pwsh|osascript|Rscript'
-_runner='npx|bunx|uvx|pnpm dlx|yarn dlx|pipx run|uv run|npm run|pnpm run|yarn run'
+_runner='npx|bunx|uvx|pnpm dlx|yarn dlx|pipx run|uv run|npm|pnpm|yarn'
 _script='py|sh|rb|js|ts|mjs|cjs|pl|php'
 # Each alternative captures the whole Tool(...) spec (trailing [^)]*\) ) so a
 # finding reports the full offending rule, not a substring truncated at the *.
@@ -178,6 +186,12 @@ extract_allowed_tools() {
 }
 
 # SKILL.md anywhere, plus markdown directly under an agents/ or commands/ dir.
+# A file under a `vendor/` path segment is a vendored upstream reference, not a
+# loadable skill/agent/command (Claude Code loads a skill from
+# skills/<name>/SKILL.md, not from a nested vendor/ copy), so its `allowed-tools`
+# never take effect and must not be flagged. Excluding the whole `vendor/`
+# segment is a principled, path-based exclusion that covers both a direct child
+# (vendor/SKILL.md) and a nested one (vendor/<tool>/SKILL.md).
 while IFS= read -r file; do
   [[ -f "$file" ]] || continue
   at="$(extract_allowed_tools "$file")"
@@ -191,7 +205,7 @@ done < <(
     -name 'SKILL.md' \
     -o \( -name '*.md' -path '*/agents/*' \) \
     -o \( -name '*.md' -path '*/commands/*' \) \
-    \) 2>/dev/null | sort -u
+    \) ! -path '*/vendor/*' 2>/dev/null | sort -u
 )
 
 # --- Settings permissions.allow scan -----------------------------------------
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
index d1d4056ea..3c6302bde 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -68,7 +68,8 @@ D2="$TEST_TMPDIR/p1"
 mkdir -p "$D2/.claude"
 jq -n '{permissions:{allow:[
   "Bash(*)","PowerShell(*)","Bash(python*)","Bash(node *)","Bash(sh -c*)",
-  "Bash(npx *)","Bash(*.py:*)","Bash","Agent","Agent(code-reviewer)"
+  "Bash(npx *)","Bash(npm:*)","Bash(pnpm:*)","Bash(yarn:*)","Bash(npm *)",
+  "Bash(npm run *)","Bash(*.py:*)","Bash","Agent","Agent(code-reviewer)"
 ]}}' >"$D2/.claude/settings.json"
 rc=0
 OUT=$(run "$D2") || rc=$?
@@ -78,6 +79,11 @@ assert_contains "flags wildcarded interpreter python*" "$OUT" "Bash(python*)"
 assert_contains "flags interpreter node *" "$OUT" "Bash(node *)"
 assert_contains "flags sh -c*" "$OUT" "Bash(sh -c*)"
 assert_contains "flags package-manager runner npx *" "$OUT" "Bash(npx *)"
+assert_contains "flags bare package-manager wildcard npm:*" "$OUT" "Bash(npm:*)"
+assert_contains "flags bare package-manager wildcard pnpm:*" "$OUT" "Bash(pnpm:*)"
+assert_contains "flags bare package-manager wildcard yarn:*" "$OUT" "Bash(yarn:*)"
+assert_contains "flags space-form package-manager wildcard npm *" "$OUT" "Bash(npm *)"
+assert_contains "flags package-manager run wildcard npm run *" "$OUT" "Bash(npm run *)"
 assert_contains "flags script-glob interpreter *.py:*" "$OUT" "Bash(*.py:*)"
 assert_contains "flags PowerShell(*)" "$OUT" "PowerShell(*)"
 assert_contains "flags bare Bash allow" "$OUT" "bare 'Bash'"
@@ -99,7 +105,8 @@ assert_eq "scoped Agent produces exactly one finding" "1" "$(run "$D2B" --count)
 D3="$TEST_TMPDIR/narrow"
 mkdir -p "$D3/.claude"
 jq -n '{permissions:{allow:[
-  "Bash(npm test)","Bash(cargo build)","Bash(git commit *)",
+  "Bash(npm test)","Bash(npm run build)","Bash(yarn build)","Bash(pnpm install)",
+  "Bash(cargo build)","Bash(git commit *)",
   "Bash(babysit_merge.sh:*)","Read(~/.config/app/config.toml)",
   "Bash(echo Agent)","Bash(find *Agent*)"
 ]}}' >"$D3/.claude/settings.json"
@@ -177,6 +184,28 @@ assert_contains "flags bare Bash in skill frontmatter" "$OUT" "skills/bare/SKILL
 assert_contains "flags Agent rule in skill frontmatter" "$OUT" "skills/agent/SKILL.md allowed-tools: Agent allow rules are dropped"
 assert_not_contains "does NOT flag narrow git/npm skill" "$OUT" "skills/good/SKILL.md"
 
+# --- Case 6b: vendored (non-loadable) SKILL.md excluded ----------------------
+# A SKILL.md under a vendor/ path segment is a vendored upstream reference, not
+# a loadable skill, so its allowed-tools never take effect and must not be
+# flagged — while a real sibling skill with the same grant still is. Covers both
+# a direct child (vendor/SKILL.md) and a nested one (vendor/<tool>/SKILL.md).
+# Fixture root deliberately NOT named "vendor" — the exclusion matches a
+# /vendor/ path segment anywhere, so a root literally named vendor would exclude
+# every file beneath it and mask the real-vs-vendored distinction under test.
+D6B="$TEST_TMPDIR/vendor-exclusion-fixture"
+mkdir -p "$D6B/plugins/p/skills/real" \
+  "$D6B/plugins/p/skills/real/vendor" \
+  "$D6B/plugins/p/skills/real/vendor/cli"
+GRANT=$'---\nname: x\nallowed-tools: Bash(npm:*)\n---\nbody\n'
+printf '%s' "$GRANT" >"$D6B/plugins/p/skills/real/SKILL.md"
+printf '%s' "$GRANT" >"$D6B/plugins/p/skills/real/vendor/SKILL.md"
+printf '%s' "$GRANT" >"$D6B/plugins/p/skills/real/vendor/cli/SKILL.md"
+OUT=$(run "$D6B")
+assert_contains "flags the real loadable SKILL.md" "$OUT" "skills/real/SKILL.md allowed-tools"
+assert_not_contains "does NOT flag vendored direct-child SKILL.md" "$OUT" "vendor/SKILL.md"
+assert_not_contains "does NOT flag vendored nested SKILL.md" "$OUT" "vendor/cli/SKILL.md"
+assert_eq "vendored copies excluded — exactly one finding" "1" "$(run "$D6B" --count)"
+
 # --- Case 7: P3 plugin self-grant -------------------------------------------
 D7="$TEST_TMPDIR/p3"
 mkdir -p "$D7/plugins/foo/.claude-plugin" "$D7/plugins/ok/.claude-plugin"

From 0deb1ce00b226afa70d3680b820bfdd677bb6eab Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 04:11:58 -0400
Subject: [PATCH 6/8] fix(claude-config-audit): match bare-tool grants on
 top-level tokens only

A tool name embedded in another rule's payload (Bash(echo Bash),
Bash(grep PowerShell *)) satisfied the bare-tool ERE and produced false
P1 findings. Extract scan_agent's top-level tokenizer into
top_level_tokens() and exact-match tokens in scan_bare_tool.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Equ3hcHokPZMpjMzLgtcwm
---
 .../scripts/permission-rule-check.sh          | 38 +++++++++++--------
 .../scripts/permission-rule-check.test.sh     |  4 +-
 2 files changed, 25 insertions(+), 17 deletions(-)

diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
index e92334c0a..374df4b90 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -131,18 +131,29 @@ scan_rule() {
   done < <(printf '%s\n' "$text" | grep -oE "$P2_ERE" 2>/dev/null | sort -u)
 }
 
+top_level_tokens() {
+  # top_level_tokens <text> — split rule text into top-level `Tool` /
+  # `Tool(...)` tokens, one per line. The greedy `(\(...\))?` consumes a tool's
+  # whole parenthesized payload as one token, so a tool name inside another
+  # rule's payload (e.g. Bash(echo Agent), Bash(grep PowerShell *)) never
+  # surfaces as its own token.
+  printf '%s\n' "$1" | grep -oE '[A-Za-z_][A-Za-z0-9_]*(\([^)]*\))?' 2>/dev/null
+}
+
 scan_bare_tool() {
   # scan_bare_tool <text> <source-label> — flag a bare `Bash`/`PowerShell`
-  # token (the whole-tool grant that auto mode drops). scan_settings_allow
-  # exact-matches this per rule; frontmatter arrives as a blob the parenthesized
-  # P1 ERE cannot see, so it needs a token-level scan. A token immediately
-  # followed by `(` (e.g. Bash(npm test)) is a scoped rule, not a bare grant,
-  # and is excluded so an interpreter rule is not double-flagged.
-  local text="$1" src="$2" tool
+  # token (the whole-tool grant that auto mode drops). Matching runs on
+  # top-level tokens, so a scoped rule (Bash(npm test)) is not double-flagged
+  # as a bare grant, and a tool name embedded in another rule's payload
+  # (Bash(echo Bash)) is not flagged at all.
+  local text="$1" src="$2" tool tok
   for tool in Bash PowerShell; do
-    if printf '%s\n' "$text" | grep -qE "(^|[^[:alnum:]_])${tool}([^[:alnum:]_(]|\$)"; then
-      emit warning P1 "$src" "bare '$tool' allow rule grants the whole tool and is dropped in auto mode. Allow a specific bare-name command instead, e.g. Bash(babysit_merge.sh:*)."
-    fi
+    while IFS= read -r tok; do
+      if [[ "$tok" == "$tool" ]]; then
+        emit warning P1 "$src" "bare '$tool' allow rule grants the whole tool and is dropped in auto mode. Allow a specific bare-name command instead, e.g. Bash(babysit_merge.sh:*)."
+        break
+      fi
+    done < <(top_level_tokens "$text")
   done
 }
 
@@ -151,12 +162,7 @@ scan_agent() {
   # `Agent` or scoped `Agent(...)`. Unlike Bash/PowerShell, a scoped Agent rule
   # is NOT a narrow carry-over: auto mode drops all Agent allow rules
   # categorically, and Agent has no bare-PATH-command analog to re-scope to.
-  #
-  # The word "Agent" must be the rule's own tool token, not a fragment inside
-  # another tool's payload (e.g. Bash(echo Agent), Bash(find *Agent*)). So the
-  # text is first split into top-level `Tool` / `Tool(...)` tokens — the greedy
-  # `(\(...\))?` consumes a tool's whole parenthesized payload as one token, so
-  # an inner "Agent" never surfaces as its own token — then only a token that IS
+  # Matching runs on top-level tokens so only a rule whose own tool token IS
   # `Agent` or begins `Agent(` is flagged.
   local text="$1" src="$2" tok
   while IFS= read -r tok; do
@@ -164,7 +170,7 @@ scan_agent() {
       emit warning P1 "$src" "Agent allow rules are dropped in auto mode and have no PATH-durable analog — remove/re-scope, or run outside auto mode."
       break
     fi
-  done < <(printf '%s\n' "$text" | grep -oE '[A-Za-z_][A-Za-z0-9_]*(\([^)]*\))?' 2>/dev/null)
+  done < <(top_level_tokens "$text")
 }
 
 # --- Frontmatter allowed-tools scan ------------------------------------------
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
index 3c6302bde..b216e03ea 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -108,11 +108,13 @@ jq -n '{permissions:{allow:[
   "Bash(npm test)","Bash(npm run build)","Bash(yarn build)","Bash(pnpm install)",
   "Bash(cargo build)","Bash(git commit *)",
   "Bash(babysit_merge.sh:*)","Read(~/.config/app/config.toml)",
-  "Bash(echo Agent)","Bash(find *Agent*)"
+  "Bash(echo Agent)","Bash(find *Agent*)",
+  "Bash(echo Bash)","Bash(grep PowerShell *)"
 ]}}' >"$D3/.claude/settings.json"
 OUT=$(run "$D3")
 assert_contains "clean narrow ruleset reports none" "$OUT" "No fragile permission grants"
 assert_not_contains "word 'Agent' inside a Bash payload is not an Agent finding" "$OUT" "Agent allow rules are dropped"
+assert_not_contains "tool name inside a Bash payload is not a bare-tool finding" "$OUT" "bare '"
 assert_eq "narrow ruleset count == 0" "0" "$(run "$D3" --count)"
 
 # --- Case 4: P2 hardcoded machine paths -------------------------------------

From 885a94fbf941e54eeb97a7a9ce9437aef4aa4625 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 04:23:54 -0400
Subject: [PATCH 7/8] fix(claude-config-audit): catch path-prefixed
 interpreters, spare hyphenated bare commands

Two P1 alt-2/alt-3 gaps from review:

- Bash(.venv/bin/python *) and Bash(/usr/bin/python3 *) scanned clean
  because only quotes/spaces were allowed before the interpreter name.
  Allow an optional path prefix (POSIX / or Windows \) before the
  interpreter basename.
- Bash(node-gyp:*) / Bash(npm-check-updates:*) false-flagged because
  any non-alphanumeric char counted as the post-name separator, so the
  hyphen matched and the audit told users to replace the very bare-name
  shape the convention recommends. Require a real separator
  (space, quote, :) after interpreter/runner names.

Also add the missing settings.local.json scan regression case.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Equ3hcHokPZMpjMzLgtcwm
---
 .../scripts/permission-rule-check.sh             | 13 ++++++++++---
 .../scripts/permission-rule-check.test.sh        | 16 ++++++++++++++--
 2 files changed, 24 insertions(+), 5 deletions(-)

diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
index 374df4b90..f3c14a5ec 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -80,7 +80,14 @@ fi
 # P1 — one ERE, case-sensitive on the tool name. Each alternative requires a
 # wildcard so an exact narrow rule (Bash(npm test)) never matches:
 #   1. blanket Bash(*) / PowerShell(*)
-#   2. an interpreter at the command position followed (eventually) by a *
+#   2. an interpreter at the command position followed (eventually) by a * —
+#      the interpreter may carry a path prefix (Bash(.venv/bin/python *),
+#      Bash(/usr/bin/python3 *)): a wildcarded interpreter-led grant is the
+#      same arbitrary-code shape regardless of how the interpreter is addressed.
+#      What follows the name must be a * or a real separator (space, quote, :)
+#      so a hyphenated bare PATH command that merely starts with an interpreter
+#      or runner name (Bash(node-gyp:*), Bash(npm-check-updates:*)) — the very
+#      shape the convention recommends — is not flagged
 #   3. a package-manager run/exec command followed by a * — both the run/exec
 #      subcommand forms (npx, pnpm dlx, uv run, …) and a bare package manager
 #      wildcard (Bash(npm:*), Bash(npm *)), which grants arbitrary execution
@@ -95,8 +102,8 @@ _script='py|sh|rb|js|ts|mjs|cjs|pl|php'
 # Each alternative captures the whole Tool(...) spec (trailing [^)]*\) ) so a
 # finding reports the full offending rule, not a substring truncated at the *.
 P1_ERE="(Bash|PowerShell)\\(\\*\\)"
-P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*(${_interp})([^A-Za-z0-9_)][^)]*)?\\*[^)]*\\)"
-P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*(${_runner})([^A-Za-z0-9_)][^)]*)?\\*[^)]*\\)"
+P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*([^)\"' ]*[/\\\\])?(${_interp})([\"' :][^)]*)?\\*[^)]*\\)"
+P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*(${_runner})([\"' :][^)]*)?\\*[^)]*\\)"
 P1_ERE="${P1_ERE}|(Bash|PowerShell)\\([\"' ]*\\*[^)]*\\.(${_script})[^)]*\\)"
 
 # P2 — machine home-path shapes, ASSEMBLED FROM FRAGMENTS so no contiguous
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
index b216e03ea..d92204e21 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -69,7 +69,8 @@ mkdir -p "$D2/.claude"
 jq -n '{permissions:{allow:[
   "Bash(*)","PowerShell(*)","Bash(python*)","Bash(node *)","Bash(sh -c*)",
   "Bash(npx *)","Bash(npm:*)","Bash(pnpm:*)","Bash(yarn:*)","Bash(npm *)",
-  "Bash(npm run *)","Bash(*.py:*)","Bash","Agent","Agent(code-reviewer)"
+  "Bash(npm run *)","Bash(*.py:*)","Bash","Agent","Agent(code-reviewer)",
+  "Bash(.venv/bin/python *)","Bash(/usr/bin/python3 *)"
 ]}}' >"$D2/.claude/settings.json"
 rc=0
 OUT=$(run "$D2") || rc=$?
@@ -85,6 +86,8 @@ assert_contains "flags bare package-manager wildcard yarn:*" "$OUT" "Bash(yarn:*
 assert_contains "flags space-form package-manager wildcard npm *" "$OUT" "Bash(npm *)"
 assert_contains "flags package-manager run wildcard npm run *" "$OUT" "Bash(npm run *)"
 assert_contains "flags script-glob interpreter *.py:*" "$OUT" "Bash(*.py:*)"
+assert_contains "flags venv path-prefixed interpreter" "$OUT" "Bash(.venv/bin/python *)"
+assert_contains "flags absolute path-prefixed interpreter" "$OUT" "Bash(/usr/bin/python3 *)"
 assert_contains "flags PowerShell(*)" "$OUT" "PowerShell(*)"
 assert_contains "flags bare Bash allow" "$OUT" "bare 'Bash'"
 assert_contains "flags Agent allow rule" "$OUT" "Agent allow rules are dropped"
@@ -109,7 +112,8 @@ jq -n '{permissions:{allow:[
   "Bash(cargo build)","Bash(git commit *)",
   "Bash(babysit_merge.sh:*)","Read(~/.config/app/config.toml)",
   "Bash(echo Agent)","Bash(find *Agent*)",
-  "Bash(echo Bash)","Bash(grep PowerShell *)"
+  "Bash(echo Bash)","Bash(grep PowerShell *)",
+  "Bash(node-gyp:*)","Bash(ruby-lsp:*)","Bash(npm-check-updates:*)"
 ]}}' >"$D3/.claude/settings.json"
 OUT=$(run "$D3")
 assert_contains "clean narrow ruleset reports none" "$OUT" "No fragile permission grants"
@@ -226,6 +230,14 @@ mkdir -p "$D8/.claude"
 jq -n '{permissions:{allow:["Bash(babysit_merge.sh:*)"]}}' >"$D8/.claude/settings.json"
 assert_contains "clean repo message" "$(run "$D8")" "No fragile permission grants"
 
+# --- Case 8b: settings.local.json scanned same as settings.json --------------
+D8B="$TEST_TMPDIR/local-settings"
+mkdir -p "$D8B/.claude"
+jq -n '{permissions:{allow:["Bash(python*)"]}}' >"$D8B/.claude/settings.local.json"
+OUT=$(run "$D8B")
+assert_contains "flags P1 grant in settings.local.json" "$OUT" "Bash(python*)"
+assert_contains "finding names the local settings file" "$OUT" "settings.local.json"
+
 # --- Case 9: missing jq exits 2 ---------------------------------------------
 real_bash=$(command -v bash)
 empty_path_dir="$TEST_TMPDIR/empty-path"

From 867e5f229aaefbdf65980b74f0e5d4d78270a522 Mon Sep 17 00:00:00 2001
From: Kyle Sexton <153232337+kyle-sexton@users.noreply.github.com>
Date: Tue, 14 Jul 2026 04:34:17 -0400
Subject: [PATCH 8/8] fix(claude-config-audit): version-suffixed interpreters;
 nested-paren tokenizer

Two review gaps on the previous fix round:

- Bash(python3.11 *) / Bash(/usr/bin/python3.12:*) scanned clean:
  _interp only knew python3?. Accept version suffixes via python[0-9.]*.
- top_level_tokens() stopped a rule token at the first ), so payloads
  with command substitution or inline scripts (Bash(echo $(date) Agent),
  Bash(node -e "console.log()" PowerShell)) leaked the trailing tool
  word as a top-level token and re-created embedded-tool false
  positives. Accept one level of nested parentheses in the payload; ERE
  cannot balance arbitrary depth and rule payloads realistically nest
  at most once.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Equ3hcHokPZMpjMzLgtcwm
---
 .../scripts/permission-rule-check.sh                  | 11 ++++++++---
 .../scripts/permission-rule-check.test.sh             |  8 ++++++--
 2 files changed, 14 insertions(+), 5 deletions(-)

diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
index f3c14a5ec..2dc36dd00 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.sh
@@ -96,7 +96,9 @@ fi
 #      listed separately. A fixed subcommand (Bash(npm test), Bash(npm run
 #      build)) carries no * and is not matched.
 #   4. a leading-glob command that resolves to a script (Bash(*.py:*))
-_interp='python3?|node|deno|bun|ruby|perl|php|bash|sh|zsh|pwsh|osascript|Rscript'
+# python accepts version suffixes (python3, python3.11, python2.7): pinned
+# minor-version binaries are the same interpreter-led grant shape.
+_interp='python[0-9.]*|node|deno|bun|ruby|perl|php|bash|sh|zsh|pwsh|osascript|Rscript'
 _runner='npx|bunx|uvx|pnpm dlx|yarn dlx|pipx run|uv run|npm|pnpm|yarn'
 _script='py|sh|rb|js|ts|mjs|cjs|pl|php'
 # Each alternative captures the whole Tool(...) spec (trailing [^)]*\) ) so a
@@ -143,8 +145,11 @@ top_level_tokens() {
   # `Tool(...)` tokens, one per line. The greedy `(\(...\))?` consumes a tool's
   # whole parenthesized payload as one token, so a tool name inside another
   # rule's payload (e.g. Bash(echo Agent), Bash(grep PowerShell *)) never
-  # surfaces as its own token.
-  printf '%s\n' "$1" | grep -oE '[A-Za-z_][A-Za-z0-9_]*(\([^)]*\))?' 2>/dev/null
+  # surfaces as its own token. The payload accepts one level of nested
+  # parentheses (Bash(echo $(date) Agent), Bash(node -e "log()" PowerShell))
+  # so an inner `)` does not end the token early; ERE cannot balance
+  # arbitrary depth, and rule payloads realistically nest at most once.
+  printf '%s\n' "$1" | grep -oE '[A-Za-z_][A-Za-z0-9_]*(\(([^()]|\([^()]*\))*\))?' 2>/dev/null
 }
 
 scan_bare_tool() {
diff --git a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
index d92204e21..eb878ecbe 100755
--- a/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
+++ b/plugins/claude-config-audit/skills/permission-hygiene/scripts/permission-rule-check.test.sh
@@ -70,7 +70,8 @@ jq -n '{permissions:{allow:[
   "Bash(*)","PowerShell(*)","Bash(python*)","Bash(node *)","Bash(sh -c*)",
   "Bash(npx *)","Bash(npm:*)","Bash(pnpm:*)","Bash(yarn:*)","Bash(npm *)",
   "Bash(npm run *)","Bash(*.py:*)","Bash","Agent","Agent(code-reviewer)",
-  "Bash(.venv/bin/python *)","Bash(/usr/bin/python3 *)"
+  "Bash(.venv/bin/python *)","Bash(/usr/bin/python3 *)",
+  "Bash(python3.11 *)","Bash(/usr/bin/python3.12:*)"
 ]}}' >"$D2/.claude/settings.json"
 rc=0
 OUT=$(run "$D2") || rc=$?
@@ -88,6 +89,8 @@ assert_contains "flags package-manager run wildcard npm run *" "$OUT" "Bash(npm
 assert_contains "flags script-glob interpreter *.py:*" "$OUT" "Bash(*.py:*)"
 assert_contains "flags venv path-prefixed interpreter" "$OUT" "Bash(.venv/bin/python *)"
 assert_contains "flags absolute path-prefixed interpreter" "$OUT" "Bash(/usr/bin/python3 *)"
+assert_contains "flags version-suffixed interpreter" "$OUT" "Bash(python3.11 *)"
+assert_contains "flags path-prefixed version-suffixed interpreter" "$OUT" "Bash(/usr/bin/python3.12:*)"
 assert_contains "flags PowerShell(*)" "$OUT" "PowerShell(*)"
 assert_contains "flags bare Bash allow" "$OUT" "bare 'Bash'"
 assert_contains "flags Agent allow rule" "$OUT" "Agent allow rules are dropped"
@@ -113,7 +116,8 @@ jq -n '{permissions:{allow:[
   "Bash(babysit_merge.sh:*)","Read(~/.config/app/config.toml)",
   "Bash(echo Agent)","Bash(find *Agent*)",
   "Bash(echo Bash)","Bash(grep PowerShell *)",
-  "Bash(node-gyp:*)","Bash(ruby-lsp:*)","Bash(npm-check-updates:*)"
+  "Bash(node-gyp:*)","Bash(ruby-lsp:*)","Bash(npm-check-updates:*)",
+  "Bash(echo $(date) Agent)","Bash(node -e \"console.log()\" PowerShell)"
 ]}}' >"$D3/.claude/settings.json"
 OUT=$(run "$D3")
 assert_contains "clean narrow ruleset reports none" "$OUT" "No fragile permission grants"