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

  1. 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.
  2. User-level: These are configurations that rule all projects in our machine.
  3. 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.MD just 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.


  1. “Non-Deterministic AI” can yield different outputs from the same input due to its reliance on probabilities and variability. ↩︎

  2. These are very generic numbers that don’t have into account how many CLAUDE.MD files our repo has (because it can contain many) or how much data we’re loading into the context. ↩︎

  3. “Deterministic AI” produces the same output every time for a given input, ensuring predictability and repeatability. ↩︎

  4. 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 ↩︎

  5. This particular hook (“PreToolUse”) runs before the permissions. ↩︎