claude-code - 💡(How to fix) Fix Documentation gaps in hooks reference: ExitPlanMode payload, SubagentStop output schema, $ANTHROPIC_MODEL readability, additionalContext composition, hooks.json location [1 comments, 2 participants]

The Claude Code hooks reference (https://code.claude.com/docs/en/hooks) is missing or unclear about several runtime contracts that hook authors need to make correct decisions. Bundling related documentation gaps here; happy to split into separate issues if preferred.

1. ExitPlanMode hook payload is not documented

The hooks reference details tool_input schemas for Bash, Write, Edit, Read, Glob, Grep, WebFetch, WebSearch, Agent, and AskUserQuestion. ExitPlanMode is conspicuously absent from that schema documentation.

Empirical observation (and references in other issues) suggest:

• PostToolUse(ExitPlanMode) carries tool_response.plan (the plan text) and tool_response.filePath (path to a runtime-saved plan file at ~/.claude/plans/<random>.md).
• PreToolUse(ExitPlanMode) carries the plan in tool_input only.

This inferred behavior is undocumented, leaving hook authors to reverse-engineer the schema or guess. Recommend adding ExitPlanMode to the tool_input / tool_response schema section alongside the other tools.

2. SubagentStop hook output schema is partially undocumented

The canonical hooks reference does not document:

• Whether additionalContext is supported on SubagentStop outputs (it is documented for UserPromptSubmit but the SubagentStop section is silent).
• The full input payload shape — does it carry the subagent's transcript or last assistant message for the orchestrator hook to read?
• How agent_type is derived from a custom .claude/agents/<name>.md file. Filename? Frontmatter name: field? Both must match? This determines whether matchers like "matcher": "salesforce-developer" work for user-defined subagents.

The Agent SDK docs name fields like agent_id, agent_type, agent_transcript_path, last_assistant_message, but the canonical hooks reference does not document these together with concrete examples.

3. $ANTHROPIC_MODEL readability in hook scripts

The environment-variables reference documents how to set ANTHROPIC_MODEL. It does not document whether hook scripts can read it from their environment, nor whether the value differs per event class (e.g., UserPromptSubmit vs PreToolUse vs SubagentStop).

Use case: a hook needs to make a tier-aware decision (e.g., guard a model-tier-sensitive action like entering plan mode). Without a documented way to read the active model, the hook author has to probe.

Recommend either documenting that $ANTHROPIC_MODEL is populated in hook environments (with value shape — full ID like claude-opus-4-7 or short alias like opus), or documenting an alternative mechanism for hooks to read the active model.

4. Multiple UserPromptSubmit additionalContext precedence

When multiple UserPromptSubmit hooks each emit additionalContext, the docs do not specify what happens. Possible behaviors: concatenated / last-write-wins / first-write-wins / undefined. The general "decision precedence" rule (deny > defer > ask > allow) is documented but does not cover the additionalContext case.

This matters for projects that already have one UserPromptSubmit hook (e.g., a session-init cache primer) and want to add a second one without trampling the first.

Recommend documenting the composition behavior so hook authors know whether two registrations cohabit safely.

5. .claude/hooks/hooks.json official status

The hooks reference says hooks live in ~/.claude/settings.json or .claude/settings.json under a hooks key. Some projects in the wild (including ours, inherited from earlier conventions) carry a separate .claude/hooks/hooks.json file that Claude Code appears to also load. Whether this is officially supported, deprecated, or coincidental is not documented.

Recommend stating explicitly that the canonical location is the hooks key inside settings.json, and clarifying whether .claude/hooks/hooks.json (or any other path) is also loaded.

Why this matters

Hook authors are currently reverse-engineering these contracts by writing probe hooks, or guessing and being bounced by code review when their guesses are wrong. Closing these doc gaps would let hook authors write correct specs without empirical verification rounds.

If you'd prefer separate issues for each item, happy to split — flag in a comment and I'll re-file.