[BUG] All hooks (SessionStart, Stop, UserPromptSubmit) require --debug flag to execute in v2.0.27

Resolved 💬 10 comments Opened Oct 27, 2025 by anthonyjj89 Closed Jan 12, 2026

Summary

All hook types (SessionStart, Stop, UserPromptSubmit) fail to execute in normal Claude Code operation. Hooks only fire when Claude Code is launched with the --debug flag (specifically --debug hooks), forcing users to run in verbose debug mode for basic hook functionality.

Environment

  • Claude Code Version: 2.0.27
  • Platform: macOS Darwin 24.4.0
  • Installation: npm global install (~/.claude/local/node_modules/.bin/claude)
  • Configuration: ~/.claude/settings.json

Bug Description

Observed Behavior

  1. Without --debug flag: NO hooks execute (SessionStart, Stop, UserPromptSubmit)
  • No log file creation
  • No script execution
  • No evidence of hooks being triggered
  • --verbose mode shows no hook activity
  1. With --debug flag: ALL hooks work correctly
  • Scripts execute as expected
  • Log files created
  • Proper JSON input passed to hooks
  • Hook completion messages appear

Impact

This breaks automated workflows that depend on hooks for:

  • Session preservation (SessionStart)
  • Cleanup operations (Stop)
  • Input validation (UserPromptSubmit)
  • Background processing integration

Reproduction Steps

1. Configure hooks in ~/.claude/settings.json

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/test-hook.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "/usr/local/bin/stop-hook.sh"
          }
        ]
      }
    ]
  }
}

2. Create test hook script (/usr/local/bin/test-hook.sh)

#!/bin/bash
echo "Hook executed at $(date)" >> /tmp/hook-test.log
INPUT=$(cat)
echo "Input received: $INPUT" >> /tmp/hook-test.log

3. Test without debug mode

claude
# Make some interactions
# Exit
cat /tmp/hook-test.log  # File doesn't exist or has no new entries

4. Test WITH debug mode

claude --debug
# Make some interactions
# Exit
cat /tmp/hook-test.log  # File exists with hook execution logs!

Expected Behavior

Hooks should execute in normal mode without requiring --debug flag. Debug mode should only add verbose logging, not enable core functionality.

Actual Behavior

Hooks are completely non-functional unless --debug is specified, forcing all hook-dependent workflows to run in debug mode.

Workaround

Created wrapper script at /usr/local/bin/claude that forces --debug hooks mode:

#!/bin/bash
# WORKAROUND: Claude Code 2.0.27 bug - hooks only work with --debug flag
if [[ ! "$*" =~ --debug ]]; then
    exec "/Users/ant/.claude/local/node_modules/.bin/claude" --debug hooks "$@"
else
    exec "/Users/ant/.claude/local/node_modules/.bin/claude" "$@"
fi

Note: Using --debug hooks specifically (not just --debug) enables hook-specific debugging which appears to be required for hooks to fire at all.

Additional Context

Hook types tested (all broken without --debug):

  • SessionStart - works ONLY with --debug
  • Stop - works ONLY with --debug
  • UserPromptSubmit - works ONLY with --debug

Related Issues

  • #6305 - PreToolUse/PostToolUse hooks not executing (possibly same root cause)
  • #6403 - PostToolUse hooks comprehensive testing
  • #2814 - Multiple hook system issues
  • #3091 - Hooks don't work per-project

Potential Root Cause

This suggests hook initialization logic may be incorrectly placed inside debug-mode-only code paths, preventing hook registration/firing in normal operation.

Request

Please investigate why hooks require --debug mode to function. This is a critical regression that breaks automated workflows and forces users into debug mode for basic hook functionality.

View original on GitHub ↗

This issue has 10 comments on GitHub. Read the full discussion on GitHub ↗