[BUG] Hooks Completely Non-Functional in Subdirectories (v2.0.27) - Blocking CI/CD Workflows

[dcversus]

[BUG] Hooks Completely Non-Functional in Subdirectories (v2.0.27) - Blocking CI/CD Workflows

Environment

• Claude Code Version: v2.0.27
• Platform: macOS Darwin 23.5.0
• Test Directory: /tmp/test-project/workspace/subdir (subdirectory)
• Settings Files Tested:
  • ~/.claude/settings.json (global)
  • /tmp/test-project/.claude/settings.json (project root)
  • /tmp/test-project/workspace/subdir/.claude/settings.json (working directory)

Problem Statement

All hook types (UserPromptSubmit, SessionStart, PreToolUse, PostToolUse, Stop) completely fail to execute when Claude Code runs from subdirectories. This blocks development of advanced CI/CD pipelines that rely on hooks to orchestrate automated workflows.

This appears to be a combination of Issue #8810 (subdirectory bug) and Issue #6305 (PreToolUse/PostToolUse broken), making hooks entirely unusable in real-world project structures where Claude Code is typically launched from nested directories.

Automated Reproduction Script

Run this script to reproduce the bug in a clean environment:

#!/usr/bin/env bash
# claude-hooks-reproduction-test.sh

set -e

echo "🧪 Claude Code Hooks Bug Reproduction Test"
echo "=========================================="
echo ""

# Setup test directory structure
TEST_DIR="/tmp/claude-hooks-test-$$"
mkdir -p "$TEST_DIR/workspace/subdir"
cd "$TEST_DIR"

# Create hook script
mkdir -p "$TEST_DIR/workspace/subdir/.claude/hooks"
cat > "$TEST_DIR/workspace/subdir/.claude/hooks/test-hook.sh" <<'HOOK_EOF'
#!/usr/bin/env bash
read -r input_json
echo "🎬 Hook executed! $(date)" >> /tmp/claude-hook-test.log
echo "🎬 Hook fired!" >&2
exit 0
HOOK_EOF

chmod +x "$TEST_DIR/workspace/subdir/.claude/hooks/test-hook.sh"

# Test 1: Local settings.json (working directory)
echo "Test 1: Local .claude/settings.json in working directory"
cat > "$TEST_DIR/workspace/subdir/.claude/settings.json" <<'SETTINGS_EOF'
{
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/tmp/claude-hooks-test-$$/workspace/subdir/.claude/hooks/test-hook.sh"
          }
        ]
      }
    ]
  }
}
SETTINGS_EOF

# Replace $$ with actual PID in the script path
sed -i '' "s/\\$\\$/$$/g" "$TEST_DIR/workspace/subdir/.claude/settings.json"

# Test 2: Global settings.json
echo "Test 2: Global ~/.claude/settings.json"
mkdir -p ~/.claude
cp ~/.claude/settings.json ~/.claude/settings.json.backup 2>/dev/null || true

cat > ~/.claude/settings.json <<GLOBAL_EOF
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$TEST_DIR/workspace/subdir/.claude/hooks/test-hook.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "cat > /dev/null && date '+Stop: %Y-%m-%d %H:%M:%S' >> /tmp/claude-hook-test.log"
          }
        ]
      }
    ]
  }
}
GLOBAL_EOF

# Clear test log
rm -f /tmp/claude-hook-test.log

echo ""
echo "📁 Test environment created at: $TEST_DIR"
echo "📝 Hook script: $TEST_DIR/workspace/subdir/.claude/hooks/test-hook.sh"
echo "📝 Local settings: $TEST_DIR/workspace/subdir/.claude/settings.json"
echo "📝 Global settings: ~/.claude/settings.json"
echo ""
echo "✅ Manual hook test:"
echo '{"test": true}' | "$TEST_DIR/workspace/subdir/.claude/hooks/test-hook.sh" && echo "   Script works when run manually ✓"

echo ""
echo "🚀 Next steps:"
echo "1. cd $TEST_DIR/workspace/subdir"
echo "2. claude --dangerously-skip-permissions"
echo "3. Send any message to Claude"
echo "4. Ask Claude to run: cat /tmp/claude-hook-test.log"
echo ""
echo "📊 Expected: Hook log entries appear"
echo "📊 Actual: No log file created (hooks never fire)"
echo ""
echo "Cleanup: rm -rf $TEST_DIR && mv ~/.claude/settings.json.backup ~/.claude/settings.json 2>/dev/null || true"

Reproduction Steps

From any subdirectory:

1. Run the reproduction script:

   chmod +x claude-hooks-reproduction-test.sh
   ./claude-hooks-reproduction-test.sh
   

2. Follow the instructions printed by the script:

   cd /tmp/claude-hooks-test-XXXXX/workspace/subdir
   claude --dangerously-skip-permissions
   

3. Send any message to Claude

4. Ask Claude: "Check if the hook log exists: cat /tmp/claude-hook-test.log"

Expected Result:

🎬 Hook executed! Sun Oct 26 08:30:15 WET 2025
Stop: 2025-10-26 08:30:16

Actual Result:

cat: /tmp/claude-hook-test.log: No such file or directory

---

Testing Evidence

✅ Manual Script Execution Works

$ echo '{"tool":"Bash"}' | /tmp/claude-hooks-test-12345/workspace/subdir/.claude/hooks/test-hook.sh
🎬 Hook fired!

$ cat /tmp/claude-hook-test.log
🎬 Hook executed! Sun Oct 26 08:30:15 WET 2025

❌ Claude Code Never Invokes Hooks

$ cat /tmp/claude-hook-test.log
cat: /tmp/claude-hook-test.log: No such file or directory

Despite 15+ restarts, /hooks command usage, and testing all hook types.

---

Workarounds Attempted

Approach	Result
Absolute paths in hook commands	❌ No execution
Symlink ~/.claude/settings.json to project .claude/	❌ No execution
Inline commands (no script files)	❌ No execution
All hook types (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop)	❌ None execute
/hooks command after every change	❌ No change
Complete Claude Code restarts (15+)	❌ No change

---

Expected vs. Actual Behavior

According to docs:

User settings are defined in ~/.claude/settings.json and apply to all projects.

Expected:

• Hooks in ~/.claude/settings.json execute regardless of cwd
• Hooks in local .claude/settings.json execute when present
• /hooks command reflects loaded hooks
• Hooks fire after restart

Actual (in subdirectories):

• Global hooks (~/.claude/settings.json) don't execute
• Local hooks (.claude/settings.json) don't execute
• /hooks command doesn't show configured hooks
• No hook process spawned, no logs, no errors

Actual (from ~ directory):

• Hooks reportedly work ~80-90% of the time (Issue #8810)
• Duplicate firing reported (Issue #3465)

---

Impact Assessment

Severity: 🔴 CRITICAL

Blocked Use Cases:

1. CI/CD Pipelines: Can't automate testing, validation, deployment
2. Multi-Agent Workflows: Can't orchestrate parallel sessions
3. Context Injection: Can't add project-specific context
4. Security Validation: Can't enforce command approval
5. Progress Tracking: Can't auto-update documentation
6. Quality Gates: Can't block unsafe operations

Workaround: None. Only option is always launching from ~ (impractical).

---

Related Issues

• #8810: UserPromptSubmit hooks not working in subdirectories
• #6305: PreToolUse/PostToolUse hooks not executing
• #3579: User settings hooks not loading
• #2814: Hooks system configuration issues
• #6403: PostToolUse hooks not executing despite stdin JSON
• #3465: Duplicate hook firing from home directory

---

Proposed Solutions

Option 1: Fix Subdirectory Support (Immediate)

1. Load ~/.claude/settings.json regardless of process.cwd()
2. Resolve hook paths relative to settings file location
3. Add logging: "Loaded N hooks from ~/.claude/settings.json"

Option 2: Debug Path Resolution (Root Cause)

1. Verify ~/.claude/settings.json is read when cwd != ~
2. Check working directory for hook spawning
3. Log hook loading failures

Option 3: Add /hooks debug Command

$ claude /hooks debug
✅ Global settings: ~/.claude/settings.json (5 hooks loaded)
✅ Local settings: .claude/settings.json (3 hooks loaded)
❌ Hook execution: 0 hooks fired in session
⚠️ Subdirectory issue: known bug #8810

Option 4: Provide Source Code Access

For community debugging:

• Settings loading logic
• Hook spawning mechanism
• Path resolution code

---

Request for Anthropic Team

1. Acknowledge as critical bug affecting core feature
2. Prioritize fix - hooks are advertised but broken
3. Share debugging guidance - how can community help?
4. Provide workaround - any way to make hooks work in subdirs?
5. Update docs - clarify if "hooks only work from ~" is intended

---

Testing Offer

We're happy to:

• Test patches before release
• Provide detailed logging
• Contribute documentation improvements
• Share CI/CD workflow designs

---

Summary: Hooks are completely non-functional in subdirectories (v2.0.27), blocking CI/CD use cases. Combines bugs #8810 and #6305. Needs urgent fix.

[dcversus]

🧪 Automated Reproduction Script

I've created a fully automated test script that anyone can run to reproduce this bug:

Quick test:

curl -fsSL https://gist.github.com/dcversus/e18f1566a1c5515c8da56288b4975507/raw/claude-hooks-reproduction-test.sh | bash

What it does:

1. Creates isolated test environment in /tmp/claude-hooks-test-XXXXX
2. Sets up hooks in both local .claude/settings.json and global ~/.claude/settings.json
3. Tests UserPromptSubmit, PreToolUse, SessionStart, and Stop hooks
4. Verifies hooks work manually but fail when Claude Code runs from subdirectory
5. Provides clear instructions for manual verification

Expected: Hook log entries in /tmp/claude-hook-test.log Actual: No log file created (hooks never fire)

The script backs up your existing ~/.claude/settings.json and provides cleanup instructions.

Gist: https://gist.github.com/dcversus/e18f1566a1c5515c8da56288b4975507

[dcversus]

🔍 Investigation Complete: Root Cause Analysis & Fix Recommendations

I've completed a comprehensive technical investigation of this bug. Here are the findings:

---

📊 Summary

Status: Investigation complete, but cannot implement fix (source code is closed) Root Cause: Settings loading and/or hook execution logic assumes Claude Code runs from home directory Impact: 100% failure rate from subdirectories, ~80% from home directory Fix Complexity: Low - 3 focused changes in settings/hooks modules

---

🎯 Root Cause Hypotheses (Ranked by Likelihood)

Hypothesis #1: Settings Not Loaded from Home Directory ⭐ MOST LIKELY

Problem: Global settings (~/.claude/settings.json) not loaded when process.cwd() != ~

Evidence:

• Hooks work ~80% from ~ directory
• 100% failure from subdirectories
• Absolute paths in config still fail (rules out path resolution)
• No error messages (settings silently not loaded)

Likely Code Pattern (what's probably wrong):

// ❌ BROKEN - Only checks current directory
const settingsPath = path.join(process.cwd(), '.claude/settings.json');
if (fs.existsSync(settingsPath)) {
  return loadSettings(settingsPath);
}
return {}; // No settings found!

Recommended Fix:

// ✅ CORRECT - Load from home + project root, regardless of cwd
async function loadHookSettings(): Promise<HookSettings> {
  const globalSettings = await loadSettings(
    path.join(os.homedir(), '.claude/settings.json')
  );
  
  const projectRoot = await findProjectRoot(process.cwd());
  const localSettings = await loadSettings(
    path.join(projectRoot, '.claude/settings.json')
  );
  
  // Merge: local overrides global
  return mergeSettings(globalSettings, localSettings);
}

---

Hypothesis #2: Wrong Working Directory for Hook Execution ⭐ VERY LIKELY

Problem: Hooks spawned with cwd: process.cwd() instead of project root

Evidence:

• Environment variable CLAUDE_PROJECT_DIR documented but may not be set
• Scripts expecting project-relative paths fail
• Issue #6305 reports PreToolUse/PostToolUse don't fire even from ~

Likely Code Pattern:

// ❌ BROKEN
spawn(hookCommand, {
  cwd: process.cwd(), // Wrong if Claude launched from subdirectory!
  stdio: ['pipe', 'pipe', 'pipe']
});

Recommended Fix:

// ✅ CORRECT
const projectRoot = await findProjectRoot();
spawn(hookCommand, {
  cwd: projectRoot,  // Use project root, not process.cwd()
  env: {
    ...process.env,
    CLAUDE_PROJECT_DIR: projectRoot,
    CLAUDE_ENV_FILE: path.join(projectRoot, '.claude/env')
  },
  stdio: ['pipe', 'pipe', 'pipe']
});

---

Hypothesis #3: Project Root Detection Missing or Broken

Problem: Can't find project root from nested subdirectories

Recommended Implementation:

async function findProjectRoot(startPath: string = process.cwd()): Promise<string> {
  let currentPath = startPath;
  const root = path.parse(currentPath).root;
  
  while (currentPath !== root) {
    // Check for common project markers
    const markers = ['.git', 'package.json', 'Cargo.toml', 'go.mod', '.claude'];
    
    for (const marker of markers) {
      if (await fs.promises.access(path.join(currentPath, marker)).then(() => true).catch(() => false)) {
        return currentPath;
      }
    }
    
    // Move up one directory
    currentPath = path.dirname(currentPath);
  }
  
  // Fallback to start path if no markers found
  return startPath;
}

---

🧪 Testing Strategy

Validation After Fix

Run the reproduction test (already in repo):

cd examples/hooks
./hooks_subdirectory_reproduction_test.sh

Expected results after fix:

• ✅ Hooks fire from subdirectories
• ✅ Log file /tmp/claude-hook-test.log contains entries
• ✅ No duplicate firing from home directory (Issue #3465)
• ✅ Works in non-git projects (fallback)

Test Matrix

Scenario	Settings Location	Launch From	Expected
Global only	~/.claude/settings.json	~/project/src/	✅ Hooks fire
Local only	project/.claude/settings.json	~/project/src/	✅ Hooks fire
Both	Both files	~/project/src/	✅ Merged (local wins)
Home dir	~/.claude/settings.json	~	✅ No duplicates
Deep nesting	~/.claude/settings.json	~/a/b/c/d/e/	✅ Still fires

---

📋 Implementation Checklist for Anthropic Team

Phase 1: Settings Loading

• [ ] Load ~/.claude/settings.json using os.homedir() (not process.cwd())
• [ ] Implement findProjectRoot() to search for .git, package.json, etc.
• [ ] Load local settings from {projectRoot}/.claude/settings.json
• [ ] Merge settings (local overrides global)
• [ ] Add logging: "Loaded N hooks from ~/.claude/settings.json"

Phase 2: Hook Execution

• [ ] Set cwd: projectRoot when spawning hooks
• [ ] Set CLAUDE_PROJECT_DIR environment variable
• [ ] Set CLAUDE_ENV_FILE for SessionStart hooks
• [ ] Resolve relative paths relative to settings file location

Phase 3: Testing

• [ ] Run examples/hooks/hooks_subdirectory_reproduction_test.sh
• [ ] Verify hooks fire from nested subdirectories
• [ ] Verify no duplicate firing from home directory
• [ ] Test all hook types (UserPromptSubmit, PreToolUse, etc.)
• [ ] Test in projects without git (fallback behavior)

Phase 4: Regression Prevention

• [ ] Add unit tests for loadHookSettings()
• [ ] Add unit tests for findProjectRoot()
• [ ] Add integration test for hook execution from subdirectories
• [ ] Update documentation to clarify settings precedence

---

📄 Complete Investigation Documents

I've created comprehensive technical documentation:

1. Full Investigation: See /tmp/claude-code/HOOKS_BUG_INVESTIGATION.md in the forked repo

   • Detailed root cause analysis
   • Complete code examples
   • Testing strategy
   • Related issues analysis

2. Executive Summary: See /tmp/claude-code/SUMMARY.md

   • Quick reference for decision makers
   • Fix overview
   • Impact assessment

3. Reproduction Test: Already in examples/hooks/hooks_subdirectory_reproduction_test.sh

   • Public gist: https://gist.github.com/dcversus/e18f1566a1c5515c8da56288b4975507

---

🚫 Limitations

Since Claude Code's source is proprietary, I could not:

• ❌ Access actual settings loading implementation
• ❌ Verify exact root cause in source
• ❌ Create tested pull request with fixes

However, the hypotheses are based on:

• ✅ Documented behavior from official docs
• ✅ Reproduction test results
• ✅ Analysis of related issues (#8810, #6305, #3579)
• ✅ Common patterns in similar CLI tools

---

🎯 Recommended Next Steps

1. Search source code for:

   • Settings loading: grep -r "settings.json" src/
   • Hook spawning: grep -r "spawn.*hook" src/
   • Environment setup: grep -r "CLAUDE_PROJECT_DIR" src/

2. Verify Hypothesis #1 first (most likely):

   • Check if global settings use process.cwd() instead of os.homedir()
   • This single fix may solve 80% of the problem

3. Implement fixes in order:

   • Phase 1 (settings) → Test → Phase 2 (execution) → Test → Phase 3 (validation)

4. Validate with reproduction test:

   • Should see hooks execute from all directories
   • No duplicates, no errors

---

💬 For the Community

If you're affected by this bug:

• Workaround: Always launch from project root (limited effectiveness)
• Help test: Once fix released, run reproduction test and report results
• Share config: If hooks work in your environment, share your setup

---

Bottom Line: This is a critical but fixable bug. The investigation provides clear hypotheses, implementation guidance, and testing strategy. Ready for Anthropic engineering team to implement.

Let me know if you need any clarification on the findings! 🙏

[anthonyjj89]

This appears to be the same root cause as the hook issues in v2.0.27 - hooks only work when running with --debug or --debug hooks flag.

Working Workaround:

Create a wrapper script at /usr/local/bin/claude:

#!/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

Make it executable: chmod +x /usr/local/bin/claude

This forces debug mode automatically, which resolves the hook firing issues.

See #10401 for complete investigation and related issues.

[thenickb]

+1 All my hooks are broken. My initial attempts for the workarounds also did not work, but I need to do more to know for sure.

[yuuuuww]

I added a hook according to the official manual, but it didn't work either. I once suspected that I was reading a fake manual. Then I checked the debug log. If the hook configuration is correct, it will always prompt: "Hook output does not start with {, treating as plain `text". My test environment is Windows 10, and the code example is from the official website:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \"No description\")\"' >> ~/.claude/bash-command-log.txt"
          }
        ]
      }
    ]
  }
}

[whyuan-cc]

does this still repro? I tried curl -fsSL https://gist.github.com/dcversus/e18f1566a1c5515c8da56288b4975507/raw/claude-hooks-reproduction-test.sh | bash with claude, not claude --dangerously-skip-permissions, got

the hooks are firing successfully! The log shows:

  - Session started at 09:36:55
  - Three hook executions at:
    - 09:36:58
    - 09:37:06
    - 09:37:11
  - Session stopped at 09:37:03

  The hooks appear to be working correctly.

[github-actions[bot]]

This issue has been inactive for 30 days. If the issue is still occurring, please comment to let us know. Otherwise, this issue will be automatically closed in 30 days for housekeeping purposes.