4 ファイル変更+20-2
この更新の概要
拒否ルール設定においてツール名のみ（Bash等）を指定した場合の挙動が明確化され、対象ツールがコンテキストから完全に削除される仕組みが解説されました。プロンプトキャッシュへの影響について、ツールの完全拒否はキャッシュを無効化する一方で、特定の引数パターンを制限するスコープ付きルールはキャッシュを維持する仕様が追記されています。設定ファイルの変更が実行中のセッションに即時反映される仕組みと、モデル設定などの再起動が必要な例外項目が明示されました。
@@ -17,7 +17,7 @@ When Claude requests a tool, the SDK checks permissions in this order:
Run [hooks](/en/agent-sdk/hooks) first. A hook can deny the call outright or pass it on. A hook that returns `allow` does not skip the deny and ask rules below; those are evaluated regardless of the hook result.
Check `deny` rules (from `disallowed_tools` and [settings.json](/en/settings#permission-settings)). If a deny rule matches, the tool is blocked, even in `bypassPermissions` mode. Bare-name `disallowed_tools` entries like `Bash` remove the tool from Claude's context before this evaluation begins, so only scoped rules like `Bash(rm *)` are checked at this step.
Check `deny` rules (from `disallowed_tools` and [settings.json](/en/settings#permission-settings)). If a deny rule matches, the tool is blocked, even in `bypassPermissions` mode. Bare-name deny rules like `Bash` remove the tool from Claude's context before this evaluation begins, so only scoped rules like `Bash(rm *)` are checked at this step.
Apply the active [permission mode](#permission-modes). `bypassPermissions` approves everything that reaches this step. `acceptEdits` approves file operations. Other modes fall through.
@@ -29,6 +29,8 @@ You can view and manage Claude Code's tool permissions with `/permissions`. This
Rules are evaluated in order: **deny -> ask -> allow**. The first matching rule wins, so deny rules always take precedence.
Deny rules behave differently depending on whether they name a tool or scope a pattern within one. A bare tool name like `Bash` removes the tool from Claude's context entirely, so Claude never sees it. A scoped rule like `Bash(rm *)` leaves the tool available and blocks matching calls when Claude attempts them.
Permission rules are enforced by Claude Code, not by the model. Instructions in your prompt or `CLAUDE.md` shape what Claude tries to do, but they don't change what Claude Code allows. To grant or revoke access, use `/permissions`, the rules described here, a [permission mode](/en/permission-modes), or a [PreToolUse hook](#extend-permissions-with-hooks).
## Permission modes
@@ -62,7 +64,7 @@ To match all uses of a tool, use just the tool name without parentheses:
| `WebFetch` | Matches all web fetch requests |
| `Read` | Matches all file reads |
`Bash(*)` is equivalent to `Bash` and matches all Bash commands.
`Bash(*)` is equivalent to `Bash` and matches all Bash commands. As a deny rule, both forms remove the tool from Claude's context.
### Use specifiers for fine-grained control
@@ -53,6 +53,7 @@ These actions cause the next request to miss part or all of the cache. You see a
- [Switching models](#switching-models)
- [Connecting or disconnecting an MCP server](#connecting-or-disconnecting-an-mcp-server)
- [Denying an entire tool](#denying-an-entire-tool)
- [Compacting the conversation](#compacting-the-conversation)
- [Upgrading Claude Code](#upgrading-claude-code)
@@ -70,6 +71,12 @@ Editing your MCP config does not by itself change the cache. The new config take
[MCP tool search](/en/mcp#scale-with-mcp-tool-search) reduces how much each tool contributes to the prefix by deferring full tool definitions, but the set of tool names still has to stay stable for the cache to remain valid.
### Denying an entire tool
Adding a bare tool name like `Bash` or `WebFetch` as a [deny rule](/en/permissions#manage-permissions) removes that tool from Claude's context entirely. Tool definitions sit in the system prompt layer, so adding or removing one of these rules mid-session invalidates the cache the same way an MCP server connecting or disconnecting does. The change takes effect on the next turn whether you add it through `/permissions` or by [editing a settings file directly](/en/settings#when-edits-take-effect).
Only a bare tool name, or the equivalent `Bash(*)` form, has this effect. Scoped deny rules like `Bash(rm *)`, and all allow and ask rules, don't change which tools Claude sees. Claude Code checks them when Claude attempts a call, leaving the prefix intact.
### Compacting the conversation
[Compaction](/en/context-window#what-survives-compaction) replaces your message history with a summary. By design, this invalidates the conversation layer, since the next request has a new, shorter history that doesn't share a prefix with the old one. Claude Code reuses the system prompt layer and reloads project context from disk, which cache-hits only if CLAUDE.md and memory are unchanged since the session started.
@@ -149,6 +149,15 @@ The `$schema` line in the example above points to the [official JSON schema](htt
The published schema is updated periodically and may not include settings added in the most recent CLI releases, so a validation warning on a recently documented field does not necessarily mean your configuration is invalid.
### When edits take effect
Claude Code watches your settings files and reloads them when they change, so edits to most keys apply to the running session without a restart. This includes `permissions`, `hooks`, and credential helpers like `apiKeyHelper`. The reload covers user, project, local, and managed settings, and the [`ConfigChange` hook](/en/hooks#configchange) fires for each detected change.
A few keys are read once at session start and apply on the next restart instead:
- `model`: use [`/model`](/en/model-config#setting-your-model) to switch mid-session
- [`outputStyle`](/en/output-styles): part of the system prompt, which is rebuilt on `/clear` or restart
### Available settings
`settings.json` supports a number of options: