Laurigates Claude Plugins Claude Hooks Configuration

Claude Code Hooks Configuration

Core Expertise

Configure Claude Code lifecycle hooks (all 17 events including SessionStart, Stop, PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest, WorktreeCreate, TeammateIdle, TaskCompleted, ConfigChange, and more) with proper timeout settings to prevent "Hook cancelled" errors during session management.

Hook Events

Default timeouts: command = 600s, prompt = 30s, agent = 60s. Always set explicit timeouts — it documents intent.

Hook Types

Async and Once

• async: true on command hooks: fire-and-forget, does not block the operation
• once: true on any hook handler: runs only once per session, subsequent triggers skipped

For full event reference, schemas, and examples, see .claude/rules/hooks-reference.md.

Common Issue: Hook Cancelled Error

SessionEnd hook [bash ~/.claude/session-logger.sh] failed: Hook cancelled

Root cause: Hook execution exceeds the configured timeout. With the 2.1.50 default of 10 minutes, this is now less common — but explicitly setting "timeout" in your hook config is still recommended.

Solutions (in order of preference):

1. Background subshell - Run slow operations in background, exit immediately
2. Explicit timeout - Add timeout field to hook configuration

Hook Configuration

Location

Hooks are configured in .claude/settings.json:

• User-level: ~/.claude/settings.json
• Project-level: <project>/.claude/settings.json

Structure with Timeout

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/session-logger.sh",
            "timeout": 120
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/session-setup.sh",
            "timeout": 180
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/stop-hook-git-check.sh",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Timeout Guidelines

Fixing Timeout Issues

Recommended: Background Subshell Pattern

The most portable and robust solution is to run slow operations in a background subshell and exit immediately:

#!/bin/bash
# ~/.claude/session-logger.sh
# Exits instantly, work continues in background

(
  # All slow operations go here
  echo "$(date): Session ended" >> ~/.claude/session.log
  curl -s -X POST "https://api.example.com/log" -d "session_end=$(date)"
  # Any other slow work...
) &>/dev/null &

exit 0

Why this works:

• ( ) creates a subshell for the commands
• & runs the subshell in background
• &>/dev/null prevents stdout/stderr from blocking
• exit 0 returns success immediately

Comparison of approaches:

Alternative: Increase Timeout

If you need synchronous execution, add explicit timeout to settings:

cat ~/.claude/settings.json | jq '.hooks'
# Edit to add "timeout": <seconds> to each hook

Script Optimization Patterns

Related: Starship Timeout

If you see:

[WARN] - (starship::utils): Executing command "...node" timed out.

This is a separate starship issue. Fix by adding to ~/.config/starship.toml:

command_timeout = 1000  # 1 second (default is 500ms)

For slow node version detection:

[nodejs]
disabled = false
detect_files = ["package.json"]  # Skip .nvmrc to speed up detection

[command]
command_timeout = 2000  # Increase if still timing out

Agentic Optimizations

Quick Reference

Error Handling

Best Practices

1. Use background subshell - Wrap slow operations in ( ) &>/dev/null & and exit 0
2. Set explicit timeouts - Add timeout field for hooks requiring synchronous execution
3. Test hook timing - Use time bash ~/.claude/script.sh to measure execution
4. Redirect all output - Use &>/dev/null to prevent blocking on stdout/stderr
5. Apply /hooks menu - Use Claude Code's hook menu to reload settings after changes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.