SessionEnd hooks need hard timeouts to prevent chain blocking

[rolpro]

Problem

SessionEnd hooks currently run sequentially without enforcement of maximum execution time. This architecture creates a critical bottleneck: if any hook in the chain hangs (due to slow stdin, unresponsive APIs, or large transcript processing), all subsequent hooks are blocked indefinitely.

This is particularly problematic for developers adding new hooks to the end of the chain. A single misbehaving hook earlier in the sequence can prevent new logic from ever executing, making the system unreliable and difficult to debug.

Suggested Fix

Implement a hard timeout safety net for each SessionEnd hook using setTimeout with a process.exit(0) fallback, ensuring clearTimeout is called on normal exit paths.

Recommended timeouts:

• 10s for file-only hooks
• 15s for API-calling hooks
• 30s for inference hooks

[jacobo-ortiz]

@rolpro your framing flagged the right symptom but the fix is inverted from your proposal — and there's a single-line resolution that resolves it for every PAI user. Writing this up after a deep investigation today; opening #1308 alongside.

TL;DR

Claude Code v2.1.74+ already enforces a hard SessionEnd chain timeout. The default is 1.5 seconds — for the entire chain, not per hook. Source: Claude Code hooks docs ("SessionEnd hooks have a default timeout of 1.5 seconds"); originally surfaced via anthropics/claude-code#33706.

Setting CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS (milliseconds) raises the budget. PAI v5.0.0 does not set this env var, so every user runs at the 1.5 s default.

Evidence: which hook is over budget

Standalone /usr/bin/time -p on the six SessionEnd hooks (macOS, MBP 14,2, 5 runs each, warm cache):

Position	Hook	Wall time
1	WorkCompletionLearning	<1 s
2	SessionCleanup	<1 s
3	RelationshipMemory	<1 s
4	UpdateCounts	3.05 / 3.72 / 7.42 / 6.46 / 3.74 s
5	IntegrityCheck	0.60 s
6	KVSync	0.91 s

UpdateCounts.hook.ts is the bottleneck. Its handler (hooks/handlers/UpdateCounts.ts) makes two synchronous Anthropic API calls inside refreshUsageCache:

• usage OAuth API — AbortSignal.timeout(3000) at line 214
• cost_report admin API — AbortSignal.timeout(5000) at line 234 (only when ANTHROPIC_ADMIN_API_KEY is set)

Worst case ~8 s. UpdateCounts alone exceeds the 1.5 s SessionEnd budget by 2–5× → cancelled every time. When the budget expires mid-chain, subsequent hooks never start, so users see varying numbers of Hook cancelled lines (the in-flight hook + however many were queued) depending on cancellation timing. The terminal symptom:

SessionEnd hook [$HOME/.claude/hooks/UpdateCounts.hook.ts] failed: Hook cancelled

Why a PAI-side per-hook setTimeout (your original proposal) is not the right move

The Claude Code chain budget already enforces a hard ceiling. Adding our own per-hook timer would be a parallel-and-weaker mechanism that:

• Doesn't fix the budget exceedance — the Claude Code budget still cancels the chain
• Adds maintenance surface in every hook file
• Risks racing with the harness signal in subtle ways

The single-line env-var addition delegates to the documented, harness-level knob and respects the upstream contract.

Proposed fix — #1308

  "env": {
    "PAI_DIR": "${HOME}/.claude/PAI",
    "PROJECTS_DIR": "${HOME}/Projects",
    "BASH_DEFAULT_TIMEOUT_MS": "600000",
    "API_TIMEOUT_MS": "1800000",
+   "CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS": "10000",
    "PAI_CONFIG_DIR": "${HOME}/.claude/PAI",

10 s covers UpdateCounts worst case (~8 s) with headroom for the rest of the chain. PR: #1308.

Cross-references

• [DOCS] Hooks docs are outdated for SessionEnd timeout override behavior anthropics/claude-code#33706 — docs gap that named the 1.5 s default (closed RESOLVED 2026-03-18).
• [BUG] SessionEnd hook cancelled with "Request interrupted by user" on Ctrl+C in Version 2.1.72 anthropics/claude-code#32712 — closed NOT_PLANNED. Anthropic considers the 1.5 s budget by-design; the env var is the official override.
• SessionEnd hooks are killed before completion when running async work anthropics/claude-code#41577 — closed as duplicate. Confirms the same pattern (async work in SessionEnd hooks killed before completion). Workaround given: detach via nohup — applicable to UpdateCounts in a future PR if env-var-only proves insufficient on slow networks.

What a follow-up could look like

If the env var is considered too coarse for users without ANTHROPIC_ADMIN_API_KEY set (which skips the 5 s cost_report call → worst case drops to ~3 s), a tighter 5000 ms could work for the no-admin-key majority. I went with 10 s in #1308 to cover both paths defensively — happy to adjust.

[DonovanJonesUK]

tl:DR my finding is broader — all PreToolUse hooks are also unguarded, and the fix belongs in settings.json via the native timeout field rather than in each hook's code.

my PAI instance wrote the full write up of my experience (detailed below) and when I found this issue already logged recommended adding a comment expanding the scope to PreToolUse and pointing to the settings.json timeout field as the cleaner solution — it's already supported by Claude Code's hook system and requires no hook code changes.

Hook timeouts missing from default settings.json — terminal freeze on any bun stall

Context: I hit a production failure where a Claude auto-update mid-session caused I/O contention that stalled bun. Because 14 hooks in the default settings.json have no timeout field, the stall propagated to every subsequent terminal command — ls, cd, everything — until reboot. My setup has ~/.claude on an external volume which amplified the severity, but the root cause (unguarded hooks) is universal.

The gap: Claude Code's hook system will wait indefinitely for a command hook unless a timeout is set. On any machine where bun startup is slow, an I/O spike occurs, or a hook encounters an error path it doesn't exit cleanly from, the result is a frozen terminal with no recovery short of killing the process.

Affected hooks in the current default config (all "type": "command", no timeout):

┌────────────────────────────────────────┬────────────────────────┬─────────────────────┐
│ Event │ Hook │ Recommended timeout │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ PreToolUse (Bash) │ SecurityPipeline │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ PreToolUse (Bash) │ ContextReduction │ 5s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ PreToolUse (Write/Edit/MultiEdit/Read) │ SecurityPipeline │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ PreToolUse (AskUserQuestion) │ SetQuestionTab │ 5s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ PostToolUse (AskUserQuestion) │ QuestionAnswered │ 5s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ PreCompact │ PreCompact │ 15s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionEnd │ WorkCompletionLearning │ 20s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionEnd │ SessionCleanup │ 15s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionEnd │ RelationshipMemory │ 20s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionEnd │ UpdateCounts │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionEnd │ IntegrityCheck │ 15s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionEnd │ KVSync │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionStart │ KittyEnvPersist │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ SessionStart │ LoadContext │ 15s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ Stop │ LastResponseCache │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ Stop │ ResponseTabReset │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ Stop │ VoiceCompletion │ 10s │
├────────────────────────────────────────┼────────────────────────┼─────────────────────┤
│ Stop │ DocIntegrity │ 10s │
└────────────────────────────────────────┴────────────────────────┴─────────────────────┘

Rationale for values: bun startup is ~300ms; all these hooks complete in well under their ceiling under normal conditions. The timeout only fires on abnormal stalls — I/O contention, a hook that errors without exiting, a hung subprocess. PreToolUse timeouts are tighter (5–10s) because they block every tool call. SessionEnd/Stop hooks are looser (10–20s) because they do more legitimate work. All values are conservative — the point isn't to rush legitimate work, it's to cap the blast radius of a hang.

The PreToolUse hooks are the critical ones. SecurityPipeline runs on every Bash, Read, Write, Edit, and MultiEdit. If it hangs without a timeout, the session is effectively dead.

Suggested addition to the PAI default settings.json — add "timeout": N to each hook entry per the table above. The async: true pattern already used on some PostToolUse hooks is a good complement for hooks where the result doesn't need to block the tool call.