Skip to content

README.md

Latest commit

 

History

History
51 lines (34 loc) · 1.63 KB

README.md

File metadata and controls

51 lines (34 loc) · 1.63 KB

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