[BUG] ~/.claude/settings.local.json is only applied to sessions started in $HOME — permissions and hooks silently inert elsewhere

Environment

• Claude Code v2.1.235, Linux (Fedora, kernel 7.1.8), CLI entrypoint
• No managed settings, no CLAUDE_CONFIG_DIR override

Summary

Settings placed in ~/.claude/settings.local.json (the user config home, not a project's .claude/ dir) are applied only to sessions whose working directory is $HOME. Sessions started in any other directory ignore the file entirely — permissions, hooks, and worktree config in it silently do not apply. The docs read as if this file applies like other settings scopes.

Docs

https://code.claude.com/docs/en/permissions.md ("When your local settings file needs trust"):

"in your own configuration home, meaning your home directory or any directory whose .claude subdirectory you've set as CLAUDE_CONFIG_DIR, the file applies right away without running git."

"applies right away" suggests the config-home settings.local.json is honored generally; there is no warning that it is scoped to sessions started in $HOME only.

Repro

1. Put the full permissions object — including "defaultMode": "bypassPermissions" and an allow list — in ~/.claude/settings.local.json. Ensure ~/.claude/settings.json and all project settings files contain no permissions block.
2. Probe A (home): cd ~ && claude -p 'Use the Bash tool to run exactly: touch .perm-probe-y && echo PROBE-OK' → runs, PROBE-OK, 0 permission denials. (touch is not in the allow list; only bypassPermissions explains the approval.)
3. Probe B (project): cd ~/Projects/<any-repo> && claude -p 'Use the Bash tool to run exactly: touch .perm-probe-x && echo PROBE-OK' → denied, 1 permission denial, file not created.
4. Move the same permissions object into ~/.claude/settings.json (user scope) and re-run probe B → runs, PROBE-OK.

Impact

Everything in the config-home settings.local.json is silently inert for project sessions: deny rules (in our case billing-protection denies), ask gates, hooks (a whole set of PreToolUse guard hooks never fired), and worktree config. Interactive project sessions fall back to the new auto permission mode with no indication that a configured defaultMode: bypassPermissions exists but is unread.

Ask

Either honor ~/.claude/settings.local.json as a user-scope settings file for all sessions, or document explicitly that it is only read when the session starts in the config home — and ideally warn when a config-home settings.local.json contains load-bearing keys (permissions/hooks) that will not apply elsewhere.

---
Filed via Claude Code on the user's behalf.