[DOCS] Hooks docs omit >50K output file-path preview behavior

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Hook output handling for large stdout, additionalContext, and async hook systemMessage/additionalContext payloads

Current Documentation

The hooks reference currently describes hook output as entering Claude's context directly:

Exit 0 means success. Claude Code parses stdout for JSON output fields. JSON output is only processed on exit 0. For most events, stdout is only shown in verbose mode (Ctrl+O). The exceptions are UserPromptSubmit and SessionStart, where stdout is added as context that Claude can see and act on.

After the background process exits, if the hook produced a JSON response with a systemMessage or additionalContext field, that content is delivered to Claude as context on the next conversation turn.

Related docs reinforce the same behavior model:

Text returned via additionalContext is injected as a system reminder that Claude reads as plain text.

Output JSON with additionalContext to send info to Claude. For PostToolUse hooks, exit code 2 surfaces stderr as an error but cannot block since the tool already ran. Keep output concise since it enters context without truncation.

What's Wrong or Missing?

Changelog v2.1.89 changed this behavior:

Changed hook output over 50K characters to be saved to disk with a file path + preview instead of being injected directly into context

The docs still read as if hook output that reaches Claude is always injected directly into context. They do not explain:

A. Large hook output now has a 50K spill-to-disk threshold

There is no note that outputs over 50K characters are handled differently from smaller hook outputs.

B. Oversized output is replaced by a file path plus preview

The current wording suggests Claude receives the full hook text directly, but v2.1.89 changed oversized output to a file-reference flow.

C. Hook authors are not told how this affects automation design

People building hooks for linting, testing, analysis, or policy enforcement need to know that large outputs are no longer injected in full, because that changes how much context Claude actually receives.

This leaves the hooks docs outdated for v2.1.89+ and the context-window guidance misleading.

Suggested Improvement

Update the hooks documentation to describe the large-output behavior explicitly:

• In https://code.claude.com/docs/en/hooks, add a note near hook output / additionalContext / async output handling that hook output over 50K characters is written to disk and surfaced as a file path plus preview instead of being injected in full.
• Clarify which hook-output paths are affected (plain-text output that becomes context, hookSpecificOutput.additionalContext, and async systemMessage / additionalContext, if they share the same limit).
• In https://code.claude.com/docs/en/hooks-guide, replace the unconditional "injected as a system reminder" wording with size-aware guidance.
• In https://code.claude.com/docs/en/context-window, update the "without truncation" note so it matches v2.1.89 behavior.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/hooks | Hook output, JSON output, and async hook delivery semantics |
| https://code.claude.com/docs/en/hooks-guide | Limitations text says additionalContext is injected as a system reminder |
| https://code.claude.com/docs/en/context-window | Hook example says additionalContext enters context "without truncation" |

Total scope: 3 pages affected

Source: Changelog v2.1.89

Exact changelog entry:

Changed hook output over 50K characters to be saved to disk with a file path + preview instead of being injected directly into context