[DOCS] Hooks reference missing `terminalSequence` JSON output field for notifications
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 likecontinuework across all events. These are listed in the table below. Top-leveldecisionandreasonare used by some events to block or provide feedback. *hookSpecificOutputis a nested object for events that need richer control. |continue|true| Iffalse, Claude stops processing entirely after the hook runs. | |stopReason| none | Message shown to the user whencontinueisfalse. | |suppressOutput|false| Iftrue, 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
systemMessageandadditionalContext - 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:
| Page | Line(s) | Context |
|------|---------|---------|
| https://code.claude.com/docs/en/hooks | 680-702, 1657 | JSON output field list omits terminalSequence; Notification section mentions systemMessage but not the new field |
| https://code.claude.com/docs/en/terminal-config | 64-84 | Notification guidance covers built-in notifications and command hooks, but not structured hook output for terminal sequences |
Total scope: 2 pages affected
Feature added in v2.1.141.
3 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Issue #58858 Verification
Title: [DOCS] Hooks reference missing
terminalSequenceJSON output field for notificationsIssue Date: 2026-05-13
Verification Date: 2026-05-31
Status: RESOLVED
---
Issue Summary
This issue reported that the v2.1.141 release added a
terminalSequencefield to hook JSON output so hooks can emit terminal-side effects (desktop notifications, window-title updates, and bells) without a controlling terminal. At the time it was filed, the field was not documented in the hooks reference: there was no field definition, no supported-event guidance, and no example showing how to use it.---
Verification Results
Claim 1:
terminalSequencemissing from the JSON output field tableStatus: RESOLVED
The
terminalSequencefield is now present in the JSON output field table. At https://code.claude.com/docs/en/hooks, line 706, the table includes:The hook input and output section (line 562) also cross-references the field:
Verdict: The field definition is complete and present in the documented table.
---
Claim 2: No supported-event guidance or examples for
terminalSequenceStatus: RESOLVED
The hooks page now includes a dedicated
#### Emit terminal notificationssubsection (lines 714-746) with:````bash
#!/bin/bash
Notification hook: ping the desktop when Claude Code needs attention.
input=$(cat)
title="Claude Code"
body=$(jq -r '.message // "Needs your attention"' <<<"$input")
seq=$(printf '\033]777;notify;%s;%s\007' "$title" "$body")
jq -nc --arg seq "$seq" '{terminalSequence: $seq}'
````
terminalSequencefield requires Claude Code v2.1.141 or later."{ "terminalSequence": "..." }shape is the same from any shell or language."Verdict: The documentation now provides thorough guidance on supported events, allowed sequences, and working examples.
---
Claim 3: Notification section at terminal-config lacks cross-reference to
terminalSequenceStatus: PARTIALLY RESOLVED
The terminal-config page at https://code.claude.com/docs/en/terminal-config (lines 64-94) covers desktop notifications and hook-based sounds but does not explicitly reference
terminalSequenceor the structured hook-output path. However, it links to the hooks documentation (line 86: "configure a Notification hook"), and the hooks page now thoroughly documents the field with a Notification hook example.Verdict: The cross-reference is implicit through the existing hooks link rather than explicit. Given the thorough coverage in the hooks reference itself, this is a minor gap.
---
Current State
| Claim | Status |
|-------|--------|
|
terminalSequencemissing from JSON output field table | RESOLVED || No field definition, guidance, or examples | RESOLVED |
| terminal-config lacks cross-reference | PARTIALLY RESOLVED |
---
Suggested Fix
N/A - the core issue has been resolved. The
terminalSequencefield is now fully documented in the hooks reference with a field definition, supported-sequence guidance, a Notification hook example, and cross-references from the input/output section. The terminal-config page could optionally add an explicit mention of the structured hook-output path forterminalSequence, but this is a minor enhancement given the existing hooks link.---
References
terminalSequenceterminalSequenceterminalSequencereference---
Conclusion & Recommendation
Primary Concern: The hooks reference was missing documentation for the
terminalSequenceJSON output field introduced in v2.1.141.Resolution Status: RESOLVED
Recommendation: CLOSE
The
terminalSequencefield is now thoroughly documented in the hooks reference with a complete field definition, a dedicated "Emit terminal notifications" section covering allowed sequences and supported events, a working Notification hook example, and cross-references from the general input/output section. The issue's core complaint (no documentation at all) no longer applies.This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.