How do I update Claude Code permissions?

Question
Answer
Tested by
See also

The authoritative source for permission allow-list entries is Claude Code Settings (doc/llm/claude_code_settings.org). Never edit .claude/settings.json directly.

Question

Claude Code prompted for approval on a Bash command that should be pre-approved. How do I add or fix the allow-list entry so it is approved automatically?

Answer

The most common cause is a missing ./ prefix variant. Glob patterns like Bash(projects/ores.codegen/codegen.sh *) do not match ./projects/ores.codegen/codegen.sh ... — the leading ./ is treated as part of the command string.

Step 1 — identify the failing pattern

Note the exact command string that triggered the prompt, e.g.:

./projects/ores.codegen/codegen.sh regenerate --component refdata-cpp --profile nats-handler

Step 2 — open the org source

$EDITOR doc/llm/claude_code_settings.org

Find the relevant ** Section (e.g. ** Code generation) by searching for the script name. Each section has a #+begin_src json ... #+end_src block holding the allow entries and prose explaining the covered surface.

Step 3 — add the missing entry

Add a line for the missing variant. For a ./ prefix gap:

"Bash(./projects/ores.codegen/codegen.sh *)",
"Bash(projects/ores.codegen/codegen.sh *)",

Keep both variants (with and without ./) — callers use both forms. Update the prose above the block to document the new variant. Update the #+updated: frontmatter date.

Step 4 — redeploy

./compass.sh build --direct settings

This must run outside the sandbox (dangerouslyDisableSandbox: true). Expected output:

Tangled 1 code block from claude_code_settings.org
Settings deployed to …/.claude/settings.json

Step 5 — verify

python3 -m json.tool .claude/settings.json | grep -A1 "codegen"

Confirm the new entry is present in the JSON.

Step 6 — commit

Commit both the org source and the generated JSON together so the repo stays consistent:

git add doc/llm/claude_code_settings.org .claude/settings.json
git commit -m "[settings] Add ./prefix variant for <script>"

Tested by

Manual. Triggered by a missing ./ prefix on ./projects/ores.codegen/codegen.sh (2026-06-25); fix confirmed to eliminate the permission prompt.