docs(claude-config): required-permissions.md recommends Read(...) deny globs for secrets without stating their scope

[kyle-sexton]

Problem

plugins/claude-config/skills/audit/reference/required-permissions.md recommends a
sensitive-file-deny baseline — Read(./.env), Read(./secrets/**),
Read(./.claude/settings.local.json), key/PEM/SSH patterns — as the remedy for protecting secrets,
with no statement of what a Read deny actually reaches. A reader who follows it comes away
believing the file is protected.

Reported from a consuming project after an agent, blocked on Read, read the same file through a
python -c one-liner in the shell tool with no deny firing. Both observations were routine
fallbacks after a denied Read, not adversarial bypass attempts — which is what makes the
false confidence expensive.

What the current docs actually say

Verified this session against
https://code.claude.com/docs/en/permissions#read-and-edit,
https://code.claude.com/docs/en/sandboxing, and
https://code.claude.com/docs/en/tools-reference#powershell-tool:

• Partly refuted. A Read(...) deny is not simply a separate namespace from the shell tool. It
  applies to "file commands Claude Code recognizes in Bash, such as cat, head, tail, and
  sed", plus Read/Grep/Glob/LSP, @file mentions, IDE selection context, and Edit on the same path.
• Confirmed. The rules "don't apply to arbitrary subprocesses that read or write files
  indirectly, like a Python or Node script that opens files itself." That is the real gap and it
  matches the reported observation exactly.
• The suggested fix in the report is itself the defect. Enumerating shell readers as Bash(...)
  deny globs is documented as fragile ("Bash permission patterns that try to constrain command
  arguments are fragile"), and a PreToolUse hook inspecting the same command string inherits the
  same evasion surface. Neither is a boundary.
• The documented enforcement path is the sandbox (sandbox.filesystem.denyRead,
  sandbox.credentials.files with "mode": "deny") — OS-level over every Bash command and its
  children. It does not run on native Windows, so it is unavailable in exactly the environment that
  produced the observation.

Scope

Only required-permissions.md states this recommendation; no other plugin or docs/** page does.
No plugin in this marketplace contributes permissions.* entries. guardrails'
secret-pattern-detection.sh matches Write|Edit|NotebookEdit (blocks writing secrets); its
Bash|PowerShell hooks are git/commit-scoped. Whether guardrails should grow a credential-read
matcher is a separate product call and is not proposed here.

Fix

Add a "Scope of a Read deny" subsection stating covered vs not-covered, ranking the remedies
honestly, carrying the platform limit, and flagging what upstream does not state (PowerShell-tool
read coverage; the full recognized-command set). Leave the pattern table itself unchanged — it is
the Category B presence check.

[kyle-sexton]

This was generated by AI during triage.

Triage: verified → briefed, delegable

Category: Bug (documentation states a protection it does not deliver), claude-config.

Verification. The report's own doc research is cited with the pages it was verified against, and
its conclusion is internally consistent and self-limiting rather than overclaiming: it explicitly
records one claim from the originating report as partly refuted (a Read deny is not simply a
separate namespace from the shell tool — it does reach file commands Claude Code recognizes in the
shell), and confirms only the narrower true gap (the rules do not apply to arbitrary subprocesses
that open files themselves). It also rejects the originating report's suggested fix as itself
defective, on the strength of upstream's own documented statement that shell permission patterns
constraining command arguments are fragile. That self-correction is what moves this to verified: the
item is not repeating the incoming claim, it is the result of checking it.

Redundancy check. Searched by domain concept — credential-read protection — rather than by the
report's wording:

• Only required-permissions.md in claude-config carries this recommendation; no other plugin and
  no docs/** page states it.
• No plugin in this marketplace contributes permissions.* entries, so nothing else is shipping the
  baseline.
• In guardrails, the secret-pattern detection matcher covers the write-side tools, i.e. it blocks
  writing secrets; its shell-surface handlers are git- and commit-scoped. Nothing there matches a
  credential read.

No existing implementation of the requested behavior, and no docs/out-of-scope/ ledger in this
repo.

Why delegable — no open decision in scope. The remedy is fully specified and bounded: add a
"Scope of a Read deny" subsection stating covered versus not-covered, rank the remedies honestly,
carry the platform limitation, and flag what upstream does not state. The pattern table itself is
explicitly left unchanged. The one adjacent question that would be open — whether guardrails
should grow a credential-read matcher — is explicitly declared a separate product call and out of
scope for this item, so nothing here needs a maintainer to choose.

Brief

Behavioral contract. A reader who follows claude-config's required-permissions reference must
come away knowing what a Read deny actually reaches, and must not come away believing a denied
path is protected from every read.

Acceptance:

1. The reference states the covered surface (the read/search/edit tool surface, the recognized
   file-reading shell commands, file-mention and editor-selection context) and the not-covered
   surface (a subprocess that opens the file itself) as separate, explicit lists.
2. The remedies are ranked by what each actually enforces, with the OS-level sandbox filesystem and
   credential-file controls named as the documented enforcement boundary, and pattern-matching
   approaches named as non-boundaries.
3. The platform limitation is carried: the enforcement path does not run on native Windows, which is
   the environment that produced the original observation. A reader on that platform must not be
   left believing the ranked-first remedy is available to them.
4. What upstream does not state is flagged as unknown rather than asserted — specifically the
   PowerShell-tool read coverage and the full recognized-command set — instead of being filled in by
   inference.
5. The existing pattern table is unchanged.

Fresh-docs requirement — binding on the implementer. This item's subject is documented harness
behavior, which is inside this repository's fresh-docs mandate. Do not carry this issue's citations
forward on trust: re-fetch the current permissions, sandboxing, and tools-reference pages at
implementation time and cite them. The claims recorded here were verified on the reporting date and
the mandate treats an unrefetched fact as unverified. If a refetch contradicts anything above,
the refetched page wins and the acceptance criteria should be re-derived from it rather than
reconciled against this comment.

Labels applied: priority: medium, agent-ready; raw marker cleared.