Introduction

As AI-assisted development tools become more deeply integrated into engineering workflows, developers increasingly want to automate more. One natural desire: "When this file changes, Claude should automatically do something."

This instinct comes from years of working with familiar tools—webpack watch mode, GitHub Actions on push, OS-level file watchers. So when developers first encounter Claude Code hooks, they often assume the same mental model applies.

It doesn't. And that mismatch causes real confusion.

This post unpacks exactly how Claude Code hooks work, where they don't, and how to build genuinely reliable, deterministic workflow constraints on top of them—without misunderstanding the foundation.

Background: What People Expect vs. What Hooks Actually Are

The most common misconception about Claude Code hooks is that they behave like OS-level file system event listeners—something like inotify on Linux, FSEvents on macOS, or ReadDirectoryChangesW on Windows.

Under that (incorrect) model, you'd imagine a hook that says: "Any time spec.md changes on disk, trigger this action."

That's not what hooks are.

Claude Code hooks are lifecycle event hooks internal to the Claude Code process. They trigger at specific points within Claude Code's own execution pipeline—not in response to arbitrary file system activity.

Current hook events include things like:

• session_start / session_end
• before_tool_call / after_tool_call
• before_file_write / after_file_write
• error
• command_start / command_end

These only fire when Claude Code itself is running and actively executing through those stages. If you edit a file in your editor, or another process modifies a file, or you run a shell command outside Claude Code—none of that triggers a hook. Claude Code has no file watcher and is not listening to OS-level events.

Core Concepts

The Two-Layer Model

Understanding hooks correctly requires separating two distinct layers:

Layer 1: Event Signal (deterministic)

This is whether the hook fires at all. It is controlled entirely by the Claude Code runtime. The trigger is structural and certain: a file was written by Claude Code's own process, a tool call completed, an error occurred. No LLM inference is involved in deciding whether to fire the signal. The signal carries structured metadata—file path, operation type, etc.

Layer 2: Hook Logic (your code)

Once the hook fires, what happens next is entirely up to you. You can write a shell script that does a regex match on the path, computes a hash to detect real content changes, runs a diff, or even calls out to another process. This layer is where you can introduce whatever sophistication you need.

The critical insight: fuzzy, semantic, or LLM-based judgment belongs in Layer 2, not Layer 1. Layer 1 is always binary—did this event happen or not.

What File Changes Hooks Can and Cannot Detect

This table captures the key boundary:

The pattern: hooks see changes Claude Code itself caused. Externally-originated file changes are invisible to the hook system.

Path Matching Is Deterministic, Not Fuzzy

A question that comes up naturally: does Claude Code do any smart normalization or fuzzy matching of file paths in hook rules?

No. Path matching in hooks is exact and deterministic.

• spec.md and spce.md are completely different as far as the hook system is concerned.
• Relative paths and absolute paths are not automatically equated.
• Claude Code does not "guess" that you probably meant the spec directory when you wrote a file to a different path.

If you want to handle path normalization (stripping ./, resolving symlinks, case normalization on case-insensitive file systems), you do that yourself inside your hook script using tools like realpath. The hook system will not do it for you.

This is a feature, not a limitation. Determinism is the point.

Analysis: Hooks as a Constraint System

The Session-Scoped Finite State Machine

Once you accept that hooks only fire on Claude Code-mediated file writes within an active session, an interesting design pattern emerges.

You can model a spec-driven workflow as a session-scoped finite state machine, where:

• States correspond to artefacts that have been produced (spec drafted, schema validated, summary generated, etc.)
• Transitions are triggered by file writes to specific paths
• Hooks are the transition guards that enforce ordering and correctness

In this model, a hook on after_file_write that matches spec/**/*.md becomes a mandatory checkpoint: any time Claude writes to a spec file, the hook fires, runs a validator, and either allows the session to proceed or halts it with a non-zero exit code.

This is what "engineering-grade 100% constraint" means in this context. It is not philosophical absolute certainty—it is: as long as Claude Code uses file writes to advance workflow state, it cannot bypass your defined process rules.

Hooks vs. Documentation: A Structural Comparison

There is an important architectural shift here between constraining Claude through documents (skills, system prompts, markdown instructions) versus constraining it through hooks.

Documents tell Claude what it should do. Hooks ensure it can only proceed if it does. The difference is the difference between policy and enforcement.

The Compiler Analogy

A useful mental model: treat the spec workflow like a compiler.

• Files are the intermediate representation (AST, IR)
• Hooks are the type checker and linter
• Writing a spec file is not "done"—it is only done when the hook passes
• A hook failure is a type error, not a suggestion

Under this model, "oral completions" (Claude describing what it did without writing a file) are explicitly non-events. They don't advance workflow state because they produce no observable artefact that a hook can act on. This is a design choice: only machine-observable actions count as state transitions.

Implications

Where This Design Works Well

This architecture is well-suited to workflows that are already artefact-driven:

• Spec/schema/PRD-first development pipelines
• Multi-step generation workflows where each stage produces an output file
• Consistency enforcement across related files (e.g., ensuring a schema update triggers a docs update)
• Automated validation gates that would otherwise rely on developer memory or prompt instructions

In all of these cases, the key constraint is already present: state must be advanced through file writes. Hooks can then reliably intercept and validate those writes.

Known Escape Routes (Design Boundaries, Not Bugs)

Any honest assessment of this system must name its limits:

1. Oral completions bypass hooks. If Claude describes a change without writing a file, no hook fires. Mitigation: enforce an artefact-first discipline—incomplete work must produce incomplete files, not verbal summaries.

2. Wrong paths bypass matching rules. If Claude writes to spec_draft.md instead of spec/main.md, your path-matching hook won't fire. Mitigation: hook on the inverse—detect unauthorized writes and error on them.

3. Session interruption terminates all constraints. Token limits, network drops, or process kills end the session. No hook-based system survives this. This is fundamental and shared by any session-scoped constraint mechanism.

4. Cross-session continuity is not guaranteed. Hooks do not persist state between sessions. Workflow state that must survive session boundaries needs explicit serialization (e.g., writing a status file that the next session reads).

Building Intelligent Judgment on Top of Deterministic Triggers

The correct composition of LLM judgment and hook determinism is:

Deterministic event → Deterministic path match → (Optional) intelligent judgment

Not the reverse. The hook fires on a hard signal, then—if needed—your hook script can invoke a separate process that makes a semantic judgment about whether the content change is substantive.

For example:

# after_file_write hook (simplified)
FILE="$HOOK_FILE_PATH"
 
# Hard match first
if [[ "$FILE" != spec/*.md ]]; then
  exit 0
fi
 
# Content-based check: skip if hash unchanged
NEW_HASH=$(sha256sum "$FILE" | awk '{print $1}')
PREV_HASH=$(cat .cache/spec-hashes/"$(basename $FILE)" 2>/dev/null)
 
if [[ "$NEW_HASH" == "$PREV_HASH" ]]; then
  exit 0
fi
 
# Record new hash
echo "$NEW_HASH" > .cache/spec-hashes/"$(basename $FILE)"
 
# Run validation
./scripts/validate-spec.sh "$FILE" || exit 1

This pattern is deterministic at the trigger level, efficient (hash comparison avoids redundant work), and extensible (the validation script can be as sophisticated as needed).

Conclusion

Claude Code hooks are a powerful but often misunderstood mechanism. The core clarification:

Hooks are Claude Code lifecycle event listeners, not OS-level file watchers.

They are deterministic, structural, and binary in their triggering. They fire when Claude Code's own execution pipeline reaches a specific stage—not when arbitrary file system activity occurs.

Within a single session, this is actually a strong foundation for workflow enforcement. As long as your workflow is artefact-driven—meaning Claude must write files to advance state—hooks can enforce ordering, correctness, and completeness with engineering-grade reliability.

The design philosophy worth internalizing: hooks should be smart enough to block invalid states, but should not themselves be fuzzy or model-driven. Intelligence belongs in the actions that hooks trigger, not in the triggering conditions themselves.

Documents tell Claude what to do. Hooks ensure it cannot proceed unless it does.

That is a fundamentally different kind of constraint—and for complex, multi-step AI workflows, it is the right one.