Skip to content

SessionEnd hook reports "Hook cancelled" on exit (1.5s deferred exit outlives shutdown grace) #991

Closed

Description

@JaeyoulLee

Summary

The SessionEnd hook intermittently reports Hook cancelled in Claude Code when the user exits a session:

SessionEnd hook [node "${CLAUDE_PLUGIN_ROOT}/scripts/session-end.mjs"] failed: Hook cancelled

Root cause

In src/hooks/session-end.ts (built to scripts/session-end.mjs), the hook fires best-effort POSTs to the local engine and then defers exit:

setTimeout(() => process.exit(0), 1500).unref();

Two problems:

  1. Outlives the shutdown grace. On exit, Claude Code gives SessionEnd hooks only a short grace window. The 1.5s deferred exit (plus any pending fetch socket keeping the event loop alive) means the hook process is still running when the harness tears down → the harness kills it and surfaces Hook cancelled. The session-end telemetry POST usually still goes out, so it's cosmetic — but it's noisy on every exit.

  2. .unref() defeats the intended cap. Because the in-flight fetch sockets keep the loop alive, the unref'd timer is the only thing forcing exit; if the engine is slow/unreachable the process can linger longer than expected before the timer fires.

Reproduction

  • Node 22, agentmemory 0.9.27, Claude Code plugin install.
  • Exit a session (exit). Intermittently shows the Hook cancelled line.

Fix that worked locally

Shorten the deferred exit so the hook quits well inside the harness grace, while still giving the localhost POST time to flush:

setTimeout(() => process.exit(0), 500);

This eliminated the Hook cancelled message in my testing while preserving the fire-and-forget POST. A more robust option would be to exit as soon as the primary /session/end request settles, with a small hard cap.

Minor adjacent note

scripts/session-end.mjs uses global fetch, which is absent on Node < 18 (e.g. Node 12 → ReferenceError: fetch is not defined, unhandled rejection). A typeof fetch === 'function' guard (or an explicit Node version requirement) would fail more gracefully on systems where the hook is spawned under an older node on PATH.

Affects: same pattern likely applies to other hook scripts that use the setTimeout(...).unref() exit idiom.

Activity

  1. aberenyi commented on Nov 1, 2026

    @aberenyi

    I traced this on agentmemory 0.9.31 with Claude Code 2.1.316. On my machine it happens at every exit. Two things combine.

    1. Claude Code gives a SessionEnd hook 1.5 s by default. I read this from the 2.1.316 binary. A timeout set on a SessionEnd hook raises the budget, up to 60 s. The CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS environment variable overrides it. When the budget runs out, Claude Code aborts the hook and prints Hook cancelled. The plugin's hooks.json sets no timeout on the SessionEnd hook, so it gets 1.5 s. This answers the question on #1070 about the size of the grace window.

    2. The hook needs about 3 s on a real session. I replayed session-end.mjs on a finished real session (its own transcript, about 120 stored observations). I stubbed /session/end so that nothing changed on the server. Two runs took 3.1 s and 3.2 s. All the time is in the transcript back-fill. The hook sends its 21 POST /agentmemory/observe calls in parallel, and they complete one after another over about 2.7 s. Some calls hit the hook's 3 s client timeout. The hook sends /session/end only after they settle, so it never reaches its own 1.5 s exit timer before Claude Code cancels it.

    The calls run one at a time because mem::observe takes the per-session lock obs:<sessionId> (src/functions/observe.ts, withKeyedLock). Inside the lock, every call first lists all stored observations of the session (kv.list(KV.observations(sessionId))). It does this even for a prompt that is already stored and returns early. So each back-fill call costs one full list, and the cost grows with the size of the session. A prompt that is not yet stored also waits inside the lock for vectorIndexAddGuarded, which calls the remote embedding provider. That took about 0.6 s per call with OpenRouter here. /session/end takes the same lock (api::session::end in src/triggers/api.ts), so it waits behind all of these calls.

    This is why the .unref() change (#1069, #1070) and a shorter exit timer (#992) cannot fix the message. The hook spends its time before it ever starts that timer.

    Workaround: add "CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS": "10000" to the env block of ~/.claude/settings.json.

    Possible fixes:

    • Add "timeout": 10 to the SessionEnd hook in hooks.json. Claude Code then allows up to 10 s.
    • Check for an already-stored prompt before the hook takes the lock, or check by key rather than with a full kv.list.
    • Move the embedding call out of the obs: lock.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions