I was rebuilding the Android version of my wallpaper app one evening when I asked Claude to add ./gradlew to settings.local.json so it would stop asking me every time. Claude edited the file and showed me the new line. Then the very next ./gradlew assembleDebug brought the approval prompt right back.
My first suspicion was that Claude Code simply hadn't re-read the file. There is a GitHub issue describing exactly that symptom (#41259, March 2026). I read it, felt vindicated, and restarted the session two, then three times.
It didn't help. The prompt kept coming back.
The current behavior: edits are reloaded
The official Settings page has a section called "When edits take effect." It says Claude Code watches your settings files and reloads them when they change, and that this covers permissions and hooks across user, project, local and managed settings.
That issue has since been closed. As the docs read today, when Claude rewrites settings.local.json, the new allow rule is meant to reach the running session.
A few keys are read only once, at session start. The docs call out these:
model— switch it with/model.effortLevelandmodelSettings— change them with/effort.- Removing
permissions.blockReadsOutsideWorkingDirectoriesmid-session leaves the file-tool block in place until you remove it everywhere and restart.
Adding a permission rule isn't on that list. So "restart and it'll be fine" is usually the long way round.
Four places to look before restarting
In my case the culprit was a single ask line in the project's .claude/settings.json. Nobody else uses that repo; I had written it myself months earlier and completely forgotten about it.
The permissions docs say deny rules from any scope are evaluated before allow rules, and the Settings troubleshooting section adds that an allow in your local file doesn't outrank an ask from a project or managed file. My new allow never had a chance.
When a prompt won't go away now, I go through these in order:
- The
Setting sourcesline in/status. Confirm the file you edited is actually loaded.settings.local.jsonis read from the git repository root even if you start in a subdirectory (with exceptions such as Windows or outside a repo). - ask and deny rules elsewhere. Look in user and project settings for an
askordenythat targets the same tool. - A broken file. Invalid JSON drops the whole file; a malformed rule drops just that entry. Since 2.1.327 (November 17),
/statuslists ignored permission settings, andclaude doctorexplains why. - Pending trust. If
settings.local.jsonis tracked in git, or.claudeis a symlink, Claude Code treats it as repository-supplied and holds its allow rules until you trust the folder.
I walked through each layer in detail in reading the six layers when an allow rule doesn't stop the prompt. This piece focuses on one step before that: keeping a record of whether the edit really happened and was picked up.
What to expect when Claude writes to .claude
One more property saves a lot of confusion. .claude is a protected path, and how Claude's writes to it are handled depends on the permission mode.
| Mode | Writes to .claude |
|---|---|
default, acceptEdits | Prompted every time |
auto | Decided by the classifier |
dontAsk | Denied |
bypassPermissions | Allowed |
The docs note that an allow rule such as Edit(.claude/**) doesn't change this. The prompt may offer a session-scoped option to let Claude edit this project's .claude folder.
If an unattended job runs in dontAsk and you ask it to "add that to the settings," the write itself is refused. Claude may still say it added the rule while the file stays the same — which is part of why I started keeping a record.
A ConfigChange hook that only records
Claude Code has a ConfigChange hook that runs when a settings file changes during a session. Its matchers are user_settings, project_settings, local_settings, policy_settings and skills, and the hook receives source and file_path.
The hook can also block a change. The docs are clear that a blocked change shows nothing to you or to Claude; only a debug-log line records it. A hook you meant as a logger that accidentally blocks would be the hardest bug of all to spot.
So I settled on a split: Claude edits, the hook records, and I check whether it took. The hook only writes a log and always exits 0, whatever goes wrong.
The script below compares the changed file's allow, ask and deny against the previous snapshot and appends what was added or removed to ~/.claude/config-audit/changes.jsonl. When an allow rule is added, it also lists ask and deny rules for the same tool name from the other settings files.
#!/usr/bin/env python3
"""Called from a ConfigChange hook. Records only added/removed permission rules.
Never blocks the change (always exits 0)."""
import hashlib
import json
import sys
import time
from pathlib import Path
LOG_DIR = Path.home() / ".claude" / "config-audit"
KEYS = ("allow", "ask", "deny")
def load_rules(path):
"""Return the three permission lists, or (None, reason) if unreadable."""
try:
data = json.loads(Path(path).read_text(encoding="utf-8"))
except FileNotFoundError:
return None, "missing"
except json.JSONDecodeError as e:
return None, f"invalid JSON (line {e.lineno})"
perms = data.get("permissions") or {}
return {k: sorted(set(perms.get(k) or [])) for k in KEYS}, None
def tool_of(rule):
"""'Bash(npm run *)' -> 'Bash'"""
return rule.split("(", 1)[0]
def competing_rules(cwd, changed_path, tools):
"""Collect ask/deny rules for the same tool name from the other settings files."""
others = [Path.home() / ".claude" / "settings.json",
Path(cwd) / ".claude" / "settings.json",
Path(cwd) / ".claude" / "settings.local.json"]
hits = []
for p in others:
if str(p) == str(changed_path) or not p.exists():
continue
rules, err = load_rules(p)
if err:
continue
for k in ("ask", "deny"):
hits += [f"{k} {r} <- {p}" for r in rules[k] if tool_of(r) in tools]
return hits
def main():
event = json.load(sys.stdin)
source = event.get("source", "?")
path = event.get("file_path")
if not path or source == "skills":
return
LOG_DIR.mkdir(parents=True, exist_ok=True)
snap = LOG_DIR / f"snapshot-{hashlib.sha1(path.encode()).hexdigest()[:12]}.json"
prev = json.loads(snap.read_text()) if snap.exists() else {k: [] for k in KEYS}
rules, err = load_rules(path)
entry = {"at": time.strftime("%Y-%m-%dT%H:%M:%S"), "source": source, "file": path}
if err:
entry["error"] = err # log a broken file, but keep the old snapshot
else:
for k in KEYS:
added = [r for r in rules[k] if r not in prev.get(k, [])]
removed = [r for r in prev.get(k, []) if r not in rules[k]]
if added:
entry[k + "+"] = added
if removed:
entry[k + "-"] = removed
new_tools = {tool_of(r) for r in entry.get("allow+", [])}
if new_tools:
entry["competing"] = competing_rules(event.get("cwd", "."), path, new_tools)
snap.write_text(json.dumps(rules, ensure_ascii=False))
with open(LOG_DIR / "changes.jsonl", "a", encoding="utf-8") as f:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
if __name__ == "__main__":
try:
main()
except Exception as e: # a failing hook must never stop the session
print(f"config_audit: {e}", file=sys.stderr)
sys.exit(0)Matching only on the tool name is deliberate. I didn't want the script guessing whether Bash(./gradlew *) beats Bash(./gradlew assembleDebug). It lines up the candidates; I decide whether they actually collide.
I keep the script at ~/.claude/hooks/config_audit.py and register the hook in my user settings, ~/.claude/settings.json, which I rarely ask Claude to touch.
{
"hooks": {
"ConfigChange": [
{
"hooks": [
{
"type": "command",
"command": "python3 \"$HOME/.claude/hooks/config_audit.py\""
}
]
}
]
}
}With no matcher, it fires for every settings source; the script skips skills on its own. Because there's no args, this is shell form, so the shell expands $HOME.
What it produced on my machine
Before starting Claude Code, I fed the hook's JSON in by hand. I put ask: Bash(./gradlew *) in project settings, added allow rules to the local file one at a time, and finally left a trailing comma on purpose.
echo '{"hook_event_name":"ConfigChange","source":"local_settings","cwd":"'"$PWD"'","file_path":"'"$PWD"'/.claude/settings.local.json"}' \
| python3 ~/.claude/hooks/config_audit.py; echo "exit=$?"All three runs ended with exit=0, and changes.jsonl got these lines (paths shortened):
{"source": "local_settings", "allow+": ["Bash(npm test)"], "competing": ["ask Bash(./gradlew *) <- proj/.claude/settings.json"]}
{"source": "local_settings", "allow+": ["Bash(./gradlew assembleDebug)"], "competing": ["ask Bash(./gradlew *) <- proj/.claude/settings.json"]}
{"source": "local_settings", "error": "invalid JSON (line 1)"}The first line is the initial snapshot, so every existing rule shows up as added. The gradlew ask appears next to npm test too, since the match is by tool name only. The second line is the one I missed through three restarts.
Changes this log won't see
Per the docs, rules saved with "Yes, and don't ask again", /permissions or /model don't fire ConfigChange in the session that saved them; other open sessions reading the same file do fire it.
Managed settings from the claude.ai console and macOS managed preferences don't fire it either. I treat this log as a record of direct file edits by Claude or an editor, nothing more.
The script also looks at .claude under cwd. If you start in a subdirectory, it can miss the settings.local.json at the git root as a competing source. If that matters to you, switch it to use git rev-parse --show-toplevel.
After reading the log
A new line in changes.jsonl means the file really did change. If the prompt still appears, compare the competing field with /status:
- An
askordenyincompeting: check whether it matches the same call. - Nothing there, but
/statuslists an ignored permission setting: suspect the rule's syntax. - No new line at all: the write was refused, or a different file was edited.
I covered how silently a typo'd setting gets skipped in Claude Code ignores a misspelled settings key without a word, and how I read claude doctor warnings in sorting four doctor warnings before fixing anything.
Where I draw the line now
As an indie developer, I'm the one who edits the settings and the one who lives with them. That makes it easy to trust the memory of "I just added that," and it took me three restarts to stop.
Now, whenever Claude adds a permission for me, I read the last line of changes.jsonl first and check whether anything sits in competing before going back to work.
If you try one thing, register this hook in ~/.claude/settings.json and read the line it writes the next time Claude edits your settings. For me, that one line before a restart was worth more than the restarts themselves.