claude-code: add timeouts to Entire hooks

[MuskanPaliwal]

fixes #1065

Gives each of Entire's Claude Code hooks a timeout, so Claude Code cancels a stalled entire launch and keeps going instead of waiting on it. Existing installs get the timeouts from entire doctor or entire agent add claude-code, and entire status flags configs that still lack them and points to entire doctor.

why

In #1065, macOS blocks entire before Go main() runs (_dyld_start), so nothing inside the binary can time out. Without a hook timeout, Claude Code kept waiting on the stuck hook (still blocked after 40s in testing), and stuck hook processes piled up across sessions. With a timeout set, Claude Code cancels the hook and continues.

what changed

• Each Entire hook now carries its own timeout, from one shared table that install and repair both read. Claude Code's default is 600s for command hooks and 30s for UserPromptSubmit:
  • 30s for session-start, which Claude blocks startup on. Besides a trail refresh capped at 1s, it resolves the repo and reads and writes session state, which a cold start or a large repo can slow well past that. This is still far below the 600s default.
  • 30s for user-prompt-submit, subagent-start and pre-task, which snapshot the worktree. This matches Claude Code's own UserPromptSubmit default and stays above gitrepo.StatusWalkBudget (20s), so a slow status walk degrades on its own before the hook is cancelled.
  • 120s for stop, stop-failure, subagent-stop and post-task, which write checkpoint data. Their path can spend up to 15s on a remote probe (WriteProbeFetchBudget) and 20s on a first-checkpoint status (StatusWalkBudget) before transcript work, and a 65MB transcript has been seen taking 30s (Hook timeouts: a flat 30s is wrong in both directions, and the cap is doing telemetry's job #2115).
  • None for session-end. Claude Code already gives exit hooks only a short time, and an explicit timeout would make it wait longer.
• New hooks are written with their timeout. A hook install (entire agent add claude-code or entire enable --agent claude-code) adds the timeout to existing Entire hooks that have none, keeps any timeout the user set, and says it updated outdated hooks instead of "already installed".
• entire doctor adds the missing timeouts without asking, as it already does for the retired deny rule, and does so before its hook drift check so that check reports on the repaired config. The repair only sets a timeout on an Entire hook that has none: it adds, removes and moves no hook, keeps the user's timeouts, and skips a hook type that does not parse. It reads and writes settings.json through the same helpers as install, so an empty "permissions": {} is dropped, as install drops it.
• The Claude Code drift check used by entire status and entire doctor now reports hooks as out of date whenever a plain install would rewrite them, including Entire hooks in a command shape an older CLI wrote (which the repair does not match) and hooks without their timeout. entire status now suggests entire doctor instead of entire enable --force for outdated hooks, because --force rebuilds every Entire hook and drops the timeouts and fields the user set on them. Doctor adds missing timeouts in place, and for anything else (a missing matcher, an old command shape) it suggests entire agent add <agent>, with --force only as a fallback. It does not suggest a bare entire enable, which returns early on a repo that is already enabled.
• Rewriting settings.json keeps fields Entire does not model on the user's own hooks and matchers (for example async, statusMessage, prompt hooks). Only exact-case keys are decoded, so a key like "Command" is kept as written instead of overwriting command, and an entry whose modeled field has a value Entire does not model (a fractional timeout, or an explicit "timeout": 0) is written back unchanged. Decoding resets each entry first, so bytes kept from an earlier decode never replace the entry that followed.
• The repo's own .claude/settings.json is updated to match.

test plan

• Install tests: each hook's timeout on a fresh install, timeouts added to an existing install, a user-set timeout kept, a second install not rewriting the file, user hook fields kept, and a fresh install not reported as outdated.
• Field preservation: differently-cased keys and a fractional timeout survive an install unchanged, and a fractional or explicit zero timeout on an Entire hook is neither backfilled nor reported as outdated.
• Repair tests: an untimed Entire hook next to a user's own matcher, a malformed hook type and a permissions block (only the timeout changes, a second run changes nothing), an empty "permissions": {} (dropped, as install drops it), no settings file (nothing created), and a user-set timeout (file untouched).
• Drift check: missing timeouts and an older command shape both report outdated until an install fixes them.
• Status hint: entire status points outdated hooks to entire doctor, not entire enable --force (verified RED: the output still said run 'entire enable --force').
• Re-decoding: decoding a clean entry into a value that held a fractional timeout writes back the clean entry (verified RED: the old "command":"a","timeout":1.5 came back).
• Doctor drift message: outdated Claude Code hooks point to entire agent add claude-code.
• Doctor test: a config with its timeouts removed reports out of date, is repaired to exactly what enable writes, then reports OK, and a second repair prints nothing.
• mise run check (unrelated tests that time out under full-suite load each failed once and passed when rerun: TestExternalCommand_SigintReachesPlugin, TestProbeConfigDir_AsksClaude, TestResolveClaudeConfigDir_PrefersClaudesAnswer, and the git hook backup tests TestInstallHooks_ForeignWrapperOverPreGuardEntireDoesNotRecurse and TestInstallHooks_ReclaimedChainRunsEachHookOnce)
• Manual check with the real binary in a temp repo:
  • A fresh entire enable reports only the installed hooks.
  • After the timeouts were removed by hand, entire agent add claude-code, entire enable --agent claude-code and entire doctor each restored a file byte-for-byte identical to a fresh enable, and a second doctor run printed nothing.
  • A bare entire enable on the already-enabled repo, with or without a terminal, printed "Entire is already enabled." and left the file without its timeouts.
• Manual check with real Claude Code and a fake entire on PATH that hangs forever (run with an earlier 10s value for session-start and prompt hooks):
  • session-start was killed at 9.9s and user-prompt-submit at 10.1s.
  • session-end was cut off by Claude's exit limit at 1.5s, and Claude still answered.

not in scope

• Git hooks (prepare-commit-msg, post-commit, ...) can still hang git commit in this state.
• Pi already applies a flat 10s timeout in its generated extension. Whether that suits each Pi hook is better tracked in Hook timeouts: a flat 30s is wrong in both directions, and the cap is doing telemetry's job #2115.

🤖 Generated with Claude Code

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[Copilot]

🟡 Changes recommended

Timeout migration can remove supported user hook fields and incorrectly report a modified configuration as unchanged.

1 open finding

• Report timeout backfill as a configuration change · New

What changed in this PR

Adds per-hook Claude Code timeouts to prevent stalled Entire launches from blocking sessions.

Changes:

• Adds 10s/60s timeout tiers and migration logic.
• Preserves existing nonzero user timeouts.
• Adds regression tests and updates dogfood configuration.

File	Description
hooks.go	Defines, installs, and backfills hook timeouts.
hooks_test.go	Tests timeout installation, preservation, and idempotency.
.claude/​settings.json	Applies generated timeout values.

🧠 Review effort: Balanced

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.