skip to content

In Claude Code, when should a hook run with async or asyncRewake, and what does it give up by running in the background?

level: seniorimportance: nice to knowfreq 6%

answer

  1. background, off the critical path
  2. cannot block what already happened
  3. results arrive on the next turn
  4. exit 2 wakes an idle session
  5. a -p teardown cancels it

basics

~20 s

async: 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 s

By 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
json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/typecheck-bg.sh",
            "args": [],
            "asyncRewake": true,
            "timeout": 300
          }
        ]
      }
    ]
  }
}

go deeper

for a junior

Recall that async: true runs a command hook in the background so Claude does not wait, and that such a hook cannot block anything.

for a middle

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.

for a senior

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.

for a principal

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.