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

Hook	Trigger	Default Timeout
`SessionStart`	When Claude Code session begins	600s (command)
`SessionEnd`	When session ends or `/clear` runs	600s (command)
`Stop`	When main agent stops responding	600s (command)
`SubagentStop`	When a subagent (Task tool) finishes	600s (command)
`PreToolUse`	Before a tool executes	600s (command)
`PostToolUse`	After a tool completes	600s (command)
`PostToolUseFailure`	After a tool execution fails	600s (command)
`PermissionRequest`	When Claude requests permission for a tool	600s (command)
`WorktreeCreate`	New git worktree created via EnterWorktree	600s (command)
`WorktreeRemove`	Worktree removed after session exits	600s (command)
`TeammateIdle`	Teammate in agent team goes idle	600s (command)
`TaskCompleted`	Task in shared task list marked complete	600s (command)
`ConfigChange`	Claude Code settings change at runtime	600s (command)

Default timeouts:

command

= 600s,

prompt

= 30s,

agent

= 60s. Always set explicit timeouts — it documents intent.

Hook Types

Type	How It Works	Default Timeout	Use When
`command`	Runs a shell command, reads stdin, returns exit code/JSON	600s	Deterministic rules
`http`	Sends hook data to an HTTPS endpoint	30s	Remote/centralized policy
`prompt`	Single-turn LLM call, returns `{ok: true/false}`	30s	Judgment on hook input data
`agent`	Multi-turn subagent with tool access, returns `{ok: true/false}`	60s	Verification needing file/tool access

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):

Background subshell - Run slow operations in background, exit immediately
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

json

{
  "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

Hook Type	Recommended Timeout	Use Case
SessionStart	120–300s	Tests, linters, dependency checks
SessionEnd	60–120s	Logging, cleanup, state saving
Stop / SubagentStop	30–60s	Git status checks, quick validations
PreToolUse	10–30s	Quick validations
PostToolUse	30–120s	Logging, notifications
PermissionRequest	5–15s	Keep fast for good UX

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:

bash

#!/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:

Approach	Portability	Speed	Notes
`( ) &`	bash, zsh, sh	Instant	Recommended
`disown`	Bash-only	Instant	Not POSIX
`nohup`	POSIX	Slight overhead	Overkill for hooks

Alternative: Increase Timeout

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

bash

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

Script Optimization Patterns

Optimization	Pattern
Background subshell	`( commands ) &>/dev/null &`
Fast test modes	`--bail=1` , `-x` , `--dots`
Skip heavy operations	Conditional execution
Parallel execution	Use `&` and `wait`

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

toml

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

For slow node version detection: