[BUG] [Regression] Make backgrounded hook early return behavior configurable
Preflight Checklist
- [x] I have searched existing issues and this hasn't been reported yet
- [x] This is a single bug report (please file separate reports for different bugs)
- [x] I am using the latest version of Claude Code
What's Wrong?
Version 2.1.19 introduced a change: "Fixed backgrounded hook commands not returning early, potentially causing the
session to wait on a process that was intentionally backgrounded."
This breaks workflows that rely on hook completion callbacks. My bash-notification hook mechanism works as follows:
- A background task starts via hook (e.g., async delegation to external processes)
- When the task completes, the hook triggers a notification back to the session
- Claude processes the result
With 2.1.19, the hook returns immediately before the background process finishes, breaking the notification timing
entirely. Async collaboration workflows become unusable.
What Should Happen?
The early return behavior should be configurable, not forced:
{
"hooks": {
"backgroundedHookEarlyReturn": true
}
}
- true: Hook returns immediately (2.1.19 behavior)
- false: Hook waits for completion (original behavior for completion-based callbacks)
Error Messages/Logs
Error Messages/Logs
No error message. The hook simply returns before the background process completes, causing downstream notification
logic to fail silently.
Steps to Reproduce
Steps to Reproduce
- Configure a hook that starts a background process and sends a notification on completion
- Upgrade to 2.1.19
- Trigger the hook
- Observe: hook returns immediately, notification never arrives because the process hasn't completed yet
Claude Model
None
Is this a regression?
Yes, this worked in a previous version
Last Working Version
2.1.17
Claude Code Version
2.1.19
Platform
Other
Operating System
Other Linux
Terminal/Shell
WSL (Windows Subsystem for Linux)
Additional Information
Workaround: Downgraded to 2.1.17.
This change may be beneficial for some users, but it should be opt-in rather than forced, as it breaks existing
workflows that depend on hook completion timing.
This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗