@@ -18,6 +18,20 @@ instructions: |
1818 handlers), sandbox (OS-level isolation), env (environment variables), and
1919 various global config fields (model, attribution, autoMode, etc.).
2020
21+ Gotchas to keep in mind when editing these files:
22+
23+ - Sandbox path settings use DIFFERENT prefix semantics than permission rules:
24+ `/path` means absolute (not project-relative), `~/` means home, `./` or
25+ bare path means project root. Do not confuse these with Read/Edit path rules.
26+ - When `autoMode.allow` or `autoMode.soft_deny` arrays are set, they completely
27+ replace the built-in defaults rather than merging. Review defaults via
28+ `claude auto-mode defaults` before overriding.
29+ - When `sandbox.enabled` is true, `sandbox.filesystem.allowWrite` should include
30+ the project directory and any tool output directories. An overly restrictive
31+ sandbox without necessary write paths will cause tool failures.
32+ - The `attribution` object supersedes the deprecated `includeCoAuthoredBy`
33+ boolean. Prefer `attribution` for new configurations.
34+
2135matchers :
2236 - " .claude/settings.json"
2337 - " .claude/settings.local.json"
@@ -28,11 +42,10 @@ json_schema_path: "claude_settings.schema.json"
2842
2943requirements :
3044 bash-wildcard-word-boundaries : >
31- Bash permission patterns SHOULD use a space before the wildcard to enforce
32- word boundaries: `Bash(npm run *)` matches `npm run build` but not `npmrc`.
33- Omitting the space (`Bash(npm*)`) matches any command starting with "npm"
34- including unintended matches. Patterns MUST be reviewed for unintended
35- broad matching.
45+ Bash permission patterns MUST use the `:*` style to enforce word
46+ boundaries (e.g., `Bash(npm run:*)`) and only use regular * if it is
47+ clearly a situation where the whitespace is not appropriate. Patterns
48+ MUST be reviewed for unintended broad matching.
3649
3750 read-edit-path-prefixes : >
3851 Read and Edit permission specifiers MUST use the correct path prefix
@@ -45,51 +58,17 @@ requirements:
4558 secrets, API keys, tokens, or credentials. Sensitive values MUST go in
4659 `.claude/settings.local.json` (gitignored) or environment variables.
4760
48- deny-rules-are-final : >
49- Authors SHOULD understand that deny rules cannot be overridden at any scope.
50- If a tool is denied in shared project settings, no user-level or local
51- setting can re-allow it. Deny rules SHOULD be used intentionally for
52- hard security boundaries, not for soft preferences.
53-
54- sandbox-path-semantics-differ : >
55- Sandbox path settings (`sandbox.filesystem.allowRead`, `allowWrite`, etc.)
56- use DIFFERENT prefix semantics than permission rules: `/path` means absolute
57- (not project-relative), `~/` means home directory, `./` or bare path means
58- project root. Authors MUST NOT confuse sandbox path semantics with
59- permission rule path semantics.
60-
6161 automode-not-in-shared-settings : >
6262 `autoMode` configuration MUST NOT appear in `.claude/settings.json` (shared
6363 project settings). Claude Code ignores autoMode from shared project settings
6464 to prevent malicious repos from weakening security. Use user-level or
6565 managed settings instead.
6666
67- automode-replaces-defaults : >
68- When `autoMode.allow` or `autoMode.soft_deny` arrays are set, they MUST
69- contain all desired rules because they completely replace the built-in
70- defaults rather than merging with them. Authors SHOULD review defaults via
71- `claude auto-mode defaults` before overriding.
72-
73- attribution-over-deprecated : >
74- The `attribution` object SHOULD be used instead of the deprecated
75- `includeCoAuthoredBy` boolean. If both are present, `attribution` takes
76- precedence.
77-
7867 mcp-tools-pattern-valid : >
7968 MCP tool permission patterns MUST follow the format
8069 `mcp__<server_name>__<tool_name>` or use a wildcard `mcp__<server_name>__*`
8170 for all tools from a server. The double-underscore separators are required.
82-
83- local-settings-gitignored : >
84- `.claude/settings.local.json` SHOULD be listed in `.gitignore`. This file
85- is intended for personal overrides and sensitive configuration that MUST NOT
86- be committed to version control.
87-
88- sandbox-enabled-with-paths : >
89- When `sandbox.enabled` is `true`, at minimum `sandbox.filesystem.allowWrite`
90- SHOULD include the project directory and any tool output directories.
91- An overly restrictive sandbox without necessary write paths will cause
92- tool failures.
71+ MCP tool permissions MUST NOT use `:*`.
9372
9473references :
9574 - path : " https://json.schemastore.org/claude-code-settings.json"
0 commit comments