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

Status Closed — not planned
Maintainer reply None cached
Activity 10 comments · opened Oct 27, 2025 · 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 ↗