[FEATURE] Hook Exit Code for Session Termination

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] This is a single feature request (not multiple features)

Problem Statement

Currently, hooks can block operations (exit code 2) but cannot terminate sessions. This creates two pain points:

1. One-off automation tasks require manual termination (Ctrl+D) or external script termination after completion
2. Security enforcement hooks cannot respond to detected threats by cleanly closing the session—they must rely on blocking operations instead

External process termination bypasses normal session cleanup, skipping SessionEnd hooks and resource release procedures.

Proposed Solution

Add a new hook exit code (suggest exit code 1 or exit code 3) that allows hooks to programmatically terminate the Claude Code session. This enables clean session exits for security enforcement and task automation without requiring external process termination.

This exit code should be available on all hook events except SessionEnd (specifically: PreToolUse, PermissionRequest, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, PreCompact, Notification).

Compliance Policy Enforcement

• Enforce session timeouts across hook events
• Respond to suspicious activity patterns
• Implement organization security policies without external tooling

Benefits

• Clean exit: Runs SessionEnd hooks and releases resources normally
• Unattended automation: Enables one-off sessions that self-terminate on completion
• Security: Allows hooks to enforce policies by terminating compromised sessions
• Consistency: Aligns with existing hook exit code pattern (0 = success, 2 = block)

Alternative Solutions

_No response_

Priority

Medium - Would be very helpful

Feature Category

Configuration and settings

Use Case Example

Security Enforcement

# PreToolUse hook: Block sensitive operations if session lacks recent authentication
if [[ $TOOL_NAME == "Bash" ]] && [[ $SESSION_DURATION -gt 3600 ]]; then
  echo "Session requires re-authentication" >&2
  exit 1
fi

Task Automation

# SessionStart hook: Exit automatically after background task completes
if [[ -f /tmp/task_completed ]]; then
  exit 1
fi

Additional Context

_No response_