claude-code - 💡(How to fix) Fix [DOCS] Hooks reference missing `effort.level` JSON field and `$CLAUDE_EFFORT` environment variable

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/hooks

Section/Topic

• "Hook input and output" section — Common input fields table (lines ~516–549)
• "Command hook fields" section — environment variable documentation missing
• JSON input schema examples throughout the Hook events section

Current Documentation

The Hooks reference documents the common input fields that hooks receive via stdin JSON, including session_id, transcript_path, cwd, permission_mode, and hook_event_name. The reference also documents environment variables available to hook commands, such as $CLAUDE_PROJECT_DIR and $CLAUDE_CODE_REMOTE.

However, the documentation does NOT mention:

• The effort.level field in the JSON input that reports the active effort level (low, medium, high, xhigh, or max)
• The $CLAUDE_EFFORT environment variable available to Bash tool commands and hook scripts

The changelog for v2.1.133 states:

Hooks now receive the active effort level via the effort.level JSON input field and the $CLAUDE_EFFORT environment variable, and Bash tool commands can read $CLAUDE_EFFORT

What's Wrong or Missing?

A. effort.level missing from hook JSON input schema

Hooks receive the active effort level in their JSON input, but the "Common input fields" table and individual hook event schemas do not document effort.level. Users writing hooks that need to adapt behavior based on effort level (e.g., higher verbosity for max effort) have no way to discover this field from the official docs.

B. $CLAUDE_EFFORT missing from environment variable documentation

The Hooks reference documents $CLAUDE_PROJECT_DIR and $CLAUDE_CODE_REMOTE as available environment variables, but does not mention $CLAUDE_EFFORT. This env var is available to Bash tool commands generally (per the changelog), but hook script authors would benefit from explicit documentation that it is available inside hook command context.

Suggested Improvement

Add effort.level to the "Common input fields" table in the Hooks reference:

Document $CLAUDE_EFFORT in the "Reference scripts by path" section alongside $CLAUDE_PROJECT_DIR:

• $CLAUDE_EFFORT: the current effort level (low, medium, high, xhigh, or max). Useful for hooks that need to adjust behavior based on the active effort setting.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

Total scope: 1 page affected (Hooks reference)

The effort.level field is already documented in the Status line reference with description: "Current reasoning effort (low, medium, high, xhigh, or max). Reflects the live session value, including mid-session /effort changes." The same field should be documented in the Hooks reference as part of the common input fields.

The $CLAUDE_EFFORT variable is documented in slash-commands.md and skills.md for use in skill instructions, but the same variable's availability in hook command context is not documented in the Hooks reference.