hook-development

Claude Code hooks abort when they don't emit JSON output within a timeout window. Hooks must read stdin, immediately output valid JSON, then perform background work via a detached subprocess to avoid blocking the UI and triggering operation aborted errors on PreToolUse, PostToolUse, UserPromptSubmit, Stop, and SessionStart events.

Create a hook script that reads stdin, outputs JSON immediately to satisfy the timeout requirement, then spawns a detached worker subprocess. Pass input data via environment variables to the worker, which runs asynchronously in the background while the hook returns control to Claude Code.

Yes. Environment variables are the safe and efficient method to communicate data from your hook script to the detached worker subprocess. The hook reads stdin, sets environment variables with the input data, spawns the worker detached, and returns JSON immediately.

Immediate response means your hook outputs JSON right after reading stdin to prevent Claude Code's timeout. Background work runs asynchronously in a detached subprocess afterward. Together they let hooks perform long-running tasks—like heavy computations or API calls—without aborting.

Yes. Both your hook script and worker script must be made executable using chmod +x and placed in the scripts/ directory. Claude Code requires executable permissions to trigger the hook on events like UserPromptSubmit.

PreToolUse, PostToolUse, UserPromptSubmit, Stop, and SessionStart hooks all support immediate JSON output followed by asynchronous background work. This pattern prevents timeout aborts across all hook event types.