In Claude Code, when should a hook run with async or asyncRewake, and what does it give up by running in the background?
answer
- background, off the critical path
- cannot block what already happened
- results arrive on the next turn
- exit 2 wakes an idle session
- a -p teardown cancels it
basics
~20 sasync: true runs a command hook in the background for slow work such as test runs: Claude keeps going, results arrive next turn, and the hook can never block. asyncRewake also wakes Claude at once when the script exits 2.
solid answer
~50 sBy default a hook holds Claude until it finishes. For slow, advisory work, such as a test run after each edit or a call to an external API, I add `"async": true` to a `command` hook: Claude Code starts it and moves on. The price is control: `decision`, `permissionDecision` and `continue` have no effect, because the action already completed. When the process exits, its `additionalContext` and `systemMessage` reach Claude on the next conversation turn and are not shown to the user; an idle session waits for the next interaction. `asyncRewake: true` changes that last part: exit code 2 wakes Claude immediately and shows stderr (or stdout) as a system reminder. `timeout` is not enforced on an `async` hook but is on `asyncRewake`. Each firing is its own process with no deduplication, and in a `claude -p` run any async hook still going at teardown is killed.
code
json · 18 lines{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/typecheck-bg.sh",
"args": [],
"asyncRewake": true,
"timeout": 300
}
]
}
]
}
}go deeper
Recall that async: true runs a command hook in the background so Claude does not wait, and that such a hook cannot block anything.
Explain when results arrive (next turn, to Claude, not the user), why decision fields are ignored, and how asyncRewake differs by waking Claude on exit 2.
Show the operational traps: no deduplication, no enforced timeout on async, cancellation at -p teardown, and choosing a synchronous gate when a check must hold.
Decide which checks can be advisory and asynchronous and which must block, balancing developer wait time against how late a failure is noticed.
## Why background hooks exist A **synchronous hook** blocks Claude's execution until it completes. That is exactly what a guard needs: a `PreToolUse` check must answer before the tool runs. It is the wrong shape for slow, advisory work such as a full test suite after every edit, a deployment, or a call to a slow external service, where making Claude wait minutes after each file change wrecks the loop. Claude Code offers two handler fields for this, both available only on `type: "command"` hooks. ## What changes in the background | | Synchronous (default) | `async: true` | `asyncRewake: true` | |---|---|---|---| | Claude waits for it | yes | no | no | | Can block or decide | yes, where the event can | no | no decision fields; exit 2 wakes Claude | | When results reach Claude | right away | next conversation turn | next turn, or at once on exit 2 | | `timeout` enforced | yes | no | yes | | Shown to the user | `systemMessage` is | no; delivered to Claude only | no; exit-2 output goes to Claude as a system reminder | - **No control.** Fields like `decision`, `permissionDecision` and `continue` are ignored, because the action they would have controlled has already happened. An async `PreToolUse` hook is therefore never a gate. - **Delivery.** After the process exits, Claude Code validates its JSON against the normal output schema, drops any field of the wrong type, and delivers `additionalContext` and `systemMessage` to Claude on the next turn. - **Visibility.** Completion notifications are suppressed by default; `Ctrl+O` (verbose transcript) or `--verbose` shows them. ## asyncRewake for failures that matter Plain `async` output waits for the next interaction: if the session is idle, Claude never hears about a failing test until you type something. **`asyncRewake: true`** runs the hook in the background too, but when the script exits with code **2** Claude Code wakes Claude immediately, even in an idle session, and shows the hook's stderr (or stdout, if stderr is empty) as a system reminder. A clean run exits 0 and stays silent. That makes it the shape for "type-check in the background and interrupt only when something broke". ## Pitfalls - **No deduplication.** Every firing starts a separate process. Ten quick edits start ten test runs. Debounce in the script (a lock file or PID check), narrow the matcher, or move the work to a once-per-turn `Stop` hook. - **Headless teardown.** In `claude -p`, Claude Code kills any async hook still running when the session ends and records the outcome as `cancelled`. Work that must outlive the run has to start a fully detached process. - **Unbounded runtime.** Because `timeout` is not enforced on `async` hooks, a hung script lingers; give the script its own time limit. - **Wrong tool for enforcement.** If a check must stop a merge or a stop, use a synchronous hook (or a Stop gate) instead. ## Choosing between the three 1. The check must **stop** an action: keep it synchronous (a `PreToolUse` guard or a `Stop` gate). 2. The check is **advisory and slow**, and the next turn is soon enough: `async: true`. 3. The check is slow, but a **failure must reach Claude now**, even in an idle session: `asyncRewake: true`, exiting 2 only on a real problem. 4. The work must **finish even after a headless run ends**: have the hook start a fully detached process; Claude Code will not wait for it. ## A worked configuration 1. Write `.claude/hooks/typecheck-bg.sh` to run the type checker, exit 0 when clean, and print the errors to stderr and exit 2 when not. 2. Register it on `PostToolUse` with an `Edit|Write` matcher, `asyncRewake: true` and a `timeout` sized to the checker. 3. Claude keeps editing while the check runs; a failure wakes Claude with the error text, and a pass costs nothing.
- Claude edits ten files in quick succession and your async test hook starts ten test runs. Why, and what do you change?Claude Code does not deduplicate async hooks: each firing is a separate background process. Debounce inside the script with a lock file or a PID check, narrow the matcher or the `if` filter to the files that matter, or move the suite to a `Stop` hook that runs once per turn.
- Why did an async hook's results never arrive in a claude -p run?In non-interactive mode Claude Code kills any async hook still running at teardown and finalizes it as `cancelled`. If the result must shape the run, make the hook synchronous; if the work must simply finish, have the hook start a fully detached process.
An async hook is a posted letter rather than a phone call: you carry on with your day the moment it is sent, the reply arrives later, and nothing in the reply can undo what you already did in the meantime.
- An async PreToolUse hook can still deny the tool call once it finishes.
- async: true works on any handler type, including prompt and agent hooks.
- An async hook's timeout kills it if the test suite runs too long.
- Async hook results are shown to the user as soon as the process exits.
- Claude Code skips a new async run while the previous one is still going.