UPDATE 2026-11-11 / Added diagrams, the Permissions section, fixed some typos and some information on when each when the tool-call hooks run.
It’s pretty important to have a tight control on how our Claude Code is configured. The more we understand how it’s set, the more confident we can be that our agents will do what we want them to do, and avoid unwanted consequences.
As we’re in the infancy of this tech, and things change very quickly, have in mind I’m writing this on October 2026, and things might change drastically in the future.
Understanding configuration levels
Claude has 3 levels worth mentioning
- Enterprise-level: This is the highest level and the one we have the least control. This is meant for your organization to push rules/restrictions to your harness. If you use Claude outside an organization (just for yourself), you can disregard this.
- User-level: These are configurations that rule all projects in our machine.
- Project-level: Rules that affect only the session started from that specific folder/workspace.
To make things a bit more visual, an example would look like this:
flowchart TB
E["Enterprise · set by your org<br/>block reading .env files"]
U["User-level · ~/.claude/<br/>model: opus"]
A["Project A · my-blog/.claude/<br/>nothing set"]
B["Project B · work-api/.claude/<br/>model: sonnet"]
SA(["Session in A<br/>opus · .env blocked"])
SB(["Session in B<br/>sonnet · .env blocked"])
U -->|applies to every project| A
U --> B
A --> SA
B -->|overrides the user-level model| SB
E -.->|always wins, can't be overridden| SA
E -.-> SB
The user-level sets the defaults for every project (here, model: opus). A project can override them just for its own sessions, like Project B switching to sonnet, while Project A keeps the user default. It works a lot like git’s global and local config.
The enterprise level sits on top of everything: its rules reach every session and can’t be overridden from below.
Deterministic vs non-deterministic rules and constrains
There are reasons why we would add rules or constraints in different places.
All of the options below can live at any of the levels above (~/.claude/ for the user-level, the project folder for the project-level). One difference though is CLAUDE.MD files don’t override each other like settings do. Claude loads all of them together, so our user-level and project-level instructions add up.
CLAUDE.MD
Claude’s main entry point. This file will always be read first, loaded into the context and, most of the time, be the main set of instructions.
ANYWAYS… rules like “don’t use X tool” or “never execute Y” are honestly a hit and miss. Many times I got to remind Claude to stop doing something I added in my user level
CLAUDE.MDjust to get the classic “oh right, sorry, I missed that, it won’t happen again”. Permissions or hooks are the way to go for those cases.
Keep more broad, less important information here, like “response style” or “verbosity level” because CLAUDE.MD is non-deterministic. 1
Also, keep this file as short as possible because this is information that is loaded in the “context”, that context is finite and we need it. Even though Anthropic doesn’t provide a specific number, general consensus is less that 200 lines is good, less than 60 ideal. 2
Permissions
For simple cases like “never execute Y”, the easiest option is a deny rule in settings.json. This type of rules are deterministic 3 and Claude can’t run what’s denied.
{
"permissions": {
"deny": ["Bash(rm -rf *)"]
}
}
A deny rule wins at any level, so a project can’t allow something we denied at the user-level. The catch is that it only matches the command text so a Bash(rm -rf *) won’t stop /bin/rm -rf from running. For a harder boundary, or anything more complex, we will need hooks.
Hooks
Hooks, same as permissions, are deterministic. Just like git hooks, these will always be executed upon certain events.
Based on below categories, the events are:
| Category | Events |
|---|---|
| Session | SessionStart, Setup, SessionEnd |
| Turn | UserPromptSubmit, UserPromptExpansion, Stop, StopFailure |
| Agentic Loop | PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, PostToolBatch |
| Agent/Team | SubagentStart, SubagentStop, TeammateIdle, TaskCreated, TaskCompleted |
| File/Environment | InstructionsLoaded, ConfigChange, CwdChanged, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact |
| Notifications | Notification |
And at this point in time:
| When | Hook events |
|---|---|
| Before the tool call, ahead of the permission rules | PreToolUse |
| When the call needs a permission decision (e.g. Claude is about to ask us) | PermissionRequest |
| When auto mode denies the call | PermissionDenied |
| After the call succeeds | PostToolUse |
| After the call fails | PostToolUseFailure |
| After a batch of parallel calls finishes, before Claude’s next step | PostToolBatch |
And also based on those events there’s supports for multiple handler types (per documentation 4):
| Handler Type | Description |
|---|---|
| Command hooks | Run shell commands (most common) |
| HTTP hooks | POST to an endpoint |
| Prompt hooks | Ask a Claude model to decide (e.g. allow or block) |
| Agent hooks | Spawn subagents |
| MCP tool hooks | Call MCP tools directly |
For example, this is how the “never execute Y” rule from the CLAUDE.MD section looks as a hook. It runs before every Bash command and blocks rm -rf, no matter what Claude “remembers”. In .claude/settings.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh"
}
]
}
]
}
}
And the script, .claude/hooks/block-rm.sh would be something like:
#!/bin/bash
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
jq -n '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Destructive command blocked by hook"
}
}'
fi
To visualize this whole explanation better, this is a flow diagram of how hooks and permissions would behave during our bash rm -rf example
flowchart TB
C["Claude wants to run a Bash command"] --> H{"PreToolUse hook<br/>block-rm.sh"}
H -->|"contains rm -rf<br/>(also /bin/rm -rf)"| XH["Blocked by the hook"]
H -->|"no match, or the hook failed"| P{"Permission rules<br/>deny, then ask, then allow"}
P -->|"matches Bash(rm -rf *)"| XP["Blocked by the deny rule"]
P -->|allowed| R["Command runs"]
The hook runs first, before the permission rules 5. It catches any command containing rm -rf, including the /bin/rm -rf that the deny rule misses. If the hook can’t decide (no match, or it failed, for example because jq isn’t installed), the command moves on to the permission rules, and the deny rule is still there as a safety net. Each one covers what the other can miss.
There’s no need to memorize anything here, but understanding different levels and the capabilities and limitations that exist, gives us higher chances at getting better results. That should be enough to know when to ask our agent to add a hook or a permission rule, and at what level depending our workflow.
-
“Non-Deterministic AI” can yield different outputs from the same input due to its reliance on probabilities and variability. ↩︎
-
These are very generic numbers that don’t have into account how many
CLAUDE.MDfiles our repo has (because it can contain many) or how much data we’re loading into the context. ↩︎ -
“Deterministic AI” produces the same output every time for a given input, ensuring predictability and repeatability. ↩︎
-
The documentation goes pretty deep into various topics like Lifecycle and even it provide some examples of event fires. Documentation in: https://code.claude.com/docs/en/hooks ↩︎
-
This particular hook (“PreToolUse”) runs before the permissions. ↩︎