claude-code - 💡(How to fix) Fix SessionStart hooks lack hard enforcement — LLM can silently ignore hook instructions

Summary

SessionStart hooks inject instructions into the LLM's context via additionalContext, but there is no mechanism to enforce that the model actually executes those instructions. The hook runs successfully (confirmed by hook success in output), the instructions appear in context as system-reminder, yet the model may silently skip them and respond directly to the user instead.

The problem

Hooks are designed to automate deterministic behavior at session start (e.g., loading reference files, reading configuration, running setup steps). Users rely on them for consistent session initialization.

However, the current architecture has a fundamental gap:

1. Hook executes — command runs, output is injected into context. This works reliably.
2. LLM receives context — hook output appears as system-reminder alongside the user's message.
3. LLM ignores instructions — the model prioritizes responding to the user's message over executing the hook's instructions. No error, no warning, no trace.

There is no audit log or decision trace to explain why the instructions were skipped. The model has no internal mechanism that guarantees "process all hook instructions before generating a response."

Why this matters

• Users build hooks expecting deterministic behavior. The hook system implies a contract: "this will happen at session start." In practice, it's probabilistic.
• Soft enforcement (bold text, explicit wording, memory files reminding the model to follow hooks) increases compliance but cannot guarantee it.
• Users have no way to detect or recover from silent non-compliance without manually verifying every session.

Expected behavior

Hook instructions marked as mandatory should be enforced at the system level, not left to the model's token prediction. For example:

• Option A: System-level execution — Claude Code parses structured hook output (e.g., {"actions": ["read_file: path/to/file.md"]}) and executes those actions as a system step before the model generates its first response.
• Option B: Hard gate — The model is not allowed to generate a user-facing response until all hook-specified actions are confirmed complete.
• Option C: Compliance verification — After the model responds, Claude Code verifies that required actions (file reads, tool calls) were performed and forces a retry if not.

Current workarounds (all insufficient)

• Explicit instructions in hook output ("VERPLICHT", "MUST", "BEFORE anything else")
• Persistent memory files reminding the model to follow hooks
• Feedback memories documenting past failures

All of these are soft enforcement and subject to the same probabilistic failure.

Reproduction

1. Configure a SessionStart hook with additionalContext containing explicit action instructions
2. Run /clear or start a new session
3. Observe that the hook succeeds but the model responds to the user without executing the hook instructions
4. This does not reproduce 100% of the time — that is precisely the problem

🤖 Generated with Claude Code