agent-timeout-hook

agent-timeout-hook

A Claude Code SessionStart hook that prevents subagents from freezing indefinitely by monitoring child processes and terminating any that exceed a configurable timeout.

Problem

Subagents can freeze during execution with no timeout, no error, and no recovery path, requiring manual Ctrl+C to recover the entire session (#37521).

How It Works

1. A SessionStart hook launches agent-timeout.sh when a Claude Code session begins.
2. The script spawns a background monitor that tracks direct child processes of the session.
3. Each child's first-seen time is recorded in a temp directory ($TMPDIR/agent-timeout-<pid>/).
4. If any child process exceeds AGENT_TIMEOUT seconds, the monitor sends SIGTERM.
5. The monitor exits automatically when the parent session ends.

Installation

# Requires: jq
bash install.sh

This adds a SessionStart hook to ~/.claude/settings.json. The hook is idempotent — running install.sh again is a no-op if already installed.

Configuration

Set environment variables in your shell profile (.bashrc, .zshrc, etc.):

Variable	Default	Description
AGENT_TIMEOUT	300	Seconds before a child process is killed
POLL_INTERVAL	10	Seconds between monitoring checks

Example:

export AGENT_TIMEOUT=600   # 10-minute timeout
export POLL_INTERVAL=5     # check every 5 seconds

Uninstall

Remove the SessionStart entry referencing agent-timeout from ~/.claude/settings.json.

Development

make test    # syntax check
make lint    # shellcheck