[BUG] [Regression] Make backgrounded hook early return behavior configurable

Resolved 💬 3 comments Opened Jan 25, 2026 by HanCheg0812 Closed Jan 29, 2026

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:

  1. A background task starts via hook (e.g., async delegation to external processes)
  2. When the task completes, the hook triggers a notification back to the session
  3. 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

  1. Configure a hook that starts a background process and sends a notification on completion
  2. Upgrade to 2.1.19
  3. Trigger the hook
  4. 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.

View original on GitHub ↗

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