Persistent 'Stop hook error' in Claude Code v2.7.1 despite proper configuration

# Persistent "Stop hook error" in Claude Code despite proper configuration

## Environment
- **claude-flow version**: v2.7.1 (stable)
- **Installation method**: `npm install -g claude-flow@2.7.1`
- **IDE**: Claude Code (Anthropic's official CLI)
- **OS**: Linux (GitHub Codespaces)
- **Node version**: v22.17.0

## Issue Description
The Stop hook continuously fails with "Stop hook error" messages appearing after nearly every operation in Claude Code, despite:
1. Proper installation of claude-flow v2.7.1 stable
2. Hooks being configured to use global `claude-flow` command (not npx)
3. All other hooks (PreToolUse, PostToolUse) working correctly
4. The hook command itself working when executed manually

## Current Configuration

### `.claude/settings.json` Stop Hook:
```json
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "claude-flow hooks session-end --generate-summary true --persist-state true --export-metrics true || exit 0"
}
]
}
]
```

### Environment:
```json
"env": {
"CLAUDE_FLOW_HOOKS_ENABLED": "true",
"CLAUDE_FLOW_CHECKPOINTS_ENABLED": "true"
}
```

## Reproduction Steps
1. Install claude-flow v2.7.1: `npm install -g claude-flow@2.7.1`
2. Initialize: `claude-flow init --force`
3. Update all hook commands from `npx claude-flow@alpha` to `claude-flow` (global)
4. Execute any Bash command or tool in Claude Code
5. Observe "Stop hook error" messages appearing repeatedly

## Expected Behavior
The Stop hook should:
- Execute silently when stopping background processes
- Generate session summaries without errors
- Not interfere with normal operations

## Actual Behavior
- "Stop hook error" appears 3 times after nearly every operation
- Errors persist even with `|| exit 0` fallback
- Manual execution of the hook command works perfectly:
```bash
$ claude-flow hooks session-end --generate-summary true --persist-state true --export-metrics true
✅ Session-end hook completed
```

## What We've Tried
1. ✅ Updated from alpha version to v2.7.1 stable
2. ✅ Changed from `npx claude-flow@alpha` to global `claude-flow` command
3. ✅ Added `|| exit 0` fallback to prevent failure propagation
4. ✅ Removed all `.claude/hooks/*.sh` shell script files
5. ✅ Verified hook command works when run directly
6. ❌ Setting `"Stop": []` (empty) - This stops errors but defeats the purpose

## Additional Context
- PreToolUse hooks (`pre-command`, `pre-edit`) work correctly
- PostToolUse hooks (`post-command`, `post-edit`) work correctly
- PreCompact hooks work correctly
- Only the Stop hook consistently fails

## Screenshots
The error appears like this in Claude Code:
```
● Bash(claude-flow --version && echo "---" && which claude-flow)
⎿ v2.7.1
⎿ Stop hook error
⎿ Stop hook error
⎿ Stop hook error
```

## Hypothesis
The Stop hook may be invoked in contexts where:
1. stdin/stdout are not available (background process termination)
2. The working directory or environment differs from normal execution
3. Session state or database locks prevent proper execution
4. Multiple Stop events fire simultaneously, causing race conditions

## Requested Solution
1. Make Stop hooks more resilient to execution context issues
2. Add debug logging to help diagnose why Stop hooks fail
3. Provide configuration option to disable Stop hooks without affecting other hooks
4. Document what contexts Stop hooks run in and their requirements

## Workaround
Current workaround is to disable Stop hooks entirely:
```json
"Stop": []
```

However, this loses the valuable session-end functionality.

## Impact
- Clutters terminal output with error messages
- May indicate underlying issues with hook execution
- Affects user confidence in the hook system
- Makes it difficult to see actual errors among hook errors

## System Details
```bash
$ claude-flow --version
v2.7.1
⚡ Alpha 128 - Build Optimization & Memory Coordination

$ which claude-flow
/home/codespace/nvm/current/bin/claude-flow

$ env | grep CLAUDE
CLAUDECODE=1
CLAUDE_FLOW_AUTO_COMMIT=false
CLAUDE_FLOW_AUTO_PUSH=false
CLAUDE_FLOW_HOOKS_ENABLED=true
CLAUDE_FLOW_CHECKPOINTS_ENABLED=true
```

Would appreciate guidance on how to properly configure Stop hooks or debug why they're failing in this specific context.

Start with the Stop hook configuration in .claude/settings.json and reproduce the issue using the documented claude-flow hooks session-end command in Claude Code. Compare Stop hook execution with the working PreToolUse, PostToolUse, and PreCompact hooks. Done means Stop hooks no longer produce repeated errors while retaining session-end functionality, or the failure context is documented with useful diagnostics.

Written by the indexing model from the issue text.