Allow annotating settings.json entries (esp. permissions.allow) — JSON forbids comments

Feature request: allow annotating settings.json (esp. permissions.allow) entries

Problem

~/.claude/settings.json (and project .claude/settings.json) is strict JSON, which forbids comments. That makes it impossible to annotate individual entries inline — most painfully in permissions.allow/permissions.deny, where each entry is a bare pattern string with no room to explain:

• why a rule exists,
• what it pairs with (e.g. an allow rule that only suppresses a prompt because a PreToolUse hook is the real guard),
• when/whether it's safe to remove.

This hurts auditability and safe reverts. Concrete example: I added "Bash(sed -n *)" to permissions.allow purely as ergonomics for a read-only idiom, with a PreToolUse hook (guard-sed.sh) as the actual security guard that blocks in-place sed. There is no way to record that relationship next to the allow entry — the rationale has to live in a separate README, which drifts from the file it documents. A reviewer reading settings.json cold sees an unexplained allow rule.

Requested options (any one would help)

1. Accept JSONC (// and /* */ comments) for settings.json / settings.local.json, as VS Code does for its settings. Lowest-friction; matches developer expectations.
2. Structured permission rules with an optional comment/description field, e.g. allow entries that may be either "Bash(sed -n *)" or { "pattern": "Bash(sed -n *)", "comment": "read-only; guard-sed.sh blocks in-place sed" }.
3. A sidecar annotations map keyed by rule string (less ideal — drifts when rules change).

Option 1 or 2 preferred.

Why it matters

As permission allowlists and hook setups grow, undocumented entries accumulate and become risky to touch — exactly the rules where intent matters most. Inline annotation keeps the rationale next to the rule, supporting safe audit and revert.

Environment

Claude Code CLI, user-level ~/.claude/settings.json. macOS.