claude-code - 💡(How to fix) Fix [DOCS] Hooks reference missing `terminalSequence` JSON output field for notifications [1 comments, 2 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

JSON output and Notification hooks

Current Documentation

The hooks reference currently says:

The JSON object supports three kinds of fields:

• Universal fields like continue work across all events. These are listed in the table below.
• Top-level decision and reason are used by some events to block or provide feedback.
• hookSpecificOutput is a nested object for events that need richer control.

| continue | true | If false, Claude stops processing entirely after the hook runs. | | stopReason | none | Message shown to the user when continue is false. | | suppressOutput | false | If true, omits stdout from the debug log | | systemMessage | none | Warning message shown to the user |

Later on the same page, the Notification section says:

Notification hooks cannot block or modify notifications. They are intended for side effects such as forwarding the notification to an external service. The common JSON output fields such as systemMessage apply.

What's Wrong or Missing?

The v2.1.141 release added a terminalSequence field to hook JSON output so hooks can emit terminal-side effects such as desktop notifications, window-title updates, and bells without a controlling terminal.

That field is not documented anywhere in the hooks reference: there is no field definition, no supported-event guidance, and no example showing how to use it. As a result, the current docs only point users to built-in notification settings or shell-command Notification hooks, and they do not expose the new structured-output path.

Suggested Improvement

Add terminalSequence to the JSON output field table and document it in the hooks reference with:

• what value format it accepts
• which hook events process it
• whether it can be returned alongside systemMessage and additionalContext
• short examples for a bell, a window-title update, and a terminal-driven notification

It would also help to add one cross-reference from the Notification or terminal configuration docs explaining when to use terminalSequence instead of a shell command hook.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 pages affected

Feature added in v2.1.141.