Protocol limits and replies

This reference records boundary behavior for parser and host implementers. For a capability overview, see terminal features.

CSI parameters

CSI collection has a shared limit of 32 semicolon/colon fields, including omitted fields. Opening field 33 rejects the entire command; no truncated SGR, mode, cursor, or query is dispatched. Numeric saturation is independent of this limit. CAN/SUB cancels, ESC starts a new sequence, and reset/EOF discards unfinished state. Ordinary C0 handling continues during rejection.

OSC encoding

Built-in OSC commands use UTF-8. There is no locale encoding fallback or raw 8-bit C1 termination inside payloads.

BEL or ESC \ completes OSC. CAN/SUB, reset, and EOF discard unfinished commands. Other C0 controls and DEL are ignored inside OSC. Unknown numeric commands are ignored unless a custom handler is installed. Recovery preserves later commands. Host title/notification limits count UTF-16 code units and avoid splitting a valid surrogate pair; they do not guarantee grapheme-boundary truncation.

Pointer shapes

OSC 22 ; name ST sets the mouse pointer; BEL also terminates the command. An optional = prefix is accepted. An empty name restores the host default. Supported CSS names are default, crosshair, text, wait, pointer, move, and n-resize, ne-resize, e-resize, se-resize, s-resize, sw-resize, w-resize, nw-resize.

Names are exact, case-sensitive ASCII. Invalid, unsupported, or oversized requests preserve the previous shape and never reach a custom OSC handler. The override is session-wide: screen switches, cursor save/restore, resize, and DECSTR preserves it; RIS clears it.

Pointer presentation is independent of mouse reporting and window-manipulation permission. Activatable links and prompt actions can override the application pointer. See Ghostty's basic command, the Kitty specification, and remaining extensions.

Payload limits

OSC/DCS limits count collected bytes, including family headers/separators and excluding introducers, terminators, and ignored control bytes. Graphics APC uses separate header and payload budgets.

Overflow stops collection and consumes through termination/cancellation without dispatching a truncated prefix. An oversized OSC 8 ends active link context; other rejected commands preserve prior metadata. Oversized DCS queries receive no reply. DCS terminates with ST, not BEL.

Graphics APC drains rejected payloads through ST. Unknown/malformed headers are discarded; identified transfer-limit failures can produce fixed failure replies subject to quiet flags and response permission. Its per-chunk accounting excludes the APC header, separator and terminator.

Session-integrated clipboard writes permit up to 1 MiB of decoded text by default. Standalone parsers without that integration retain the ordinary collection limit. Permissions and decoded-size limits are checked again before execution.

Query allowlists

Denying terminal responses suppresses success and failure replies alike. Unsupported queries with defined failure responses use those responses rather than echoing request text.

Kitty colors

OSC 21;key=value;… ST processes fields in order and combines query results into one reply. key=? queries, bare key restores the current host theme, and key= requests dynamic behavior. Keys are exact and case-sensitive; decimal indices accept leading zeros. Empty keys and invalid color values are ignored. Unknown keys receive encoded replies for set, reset, and query operations.

Colors accept Kitty's named colors, #RGB/6/9/12-digit forms, scaled rgb: channels, and clipped rgbi: channels. The short #RGB form uses the most significant bits (#3a7 becomes #30a070). Optional @alpha is validated but has no effect on these opaque color roles. This syntax is independent of the older OSC 4/10/11/12 parser.

Dynamic cursor colors resolve the underlying cell's foreground/background; dynamic selection colors reverse those cell colors. Fixed selection overrides use the requested colors; resetting restores host selection presentation. Foreground, background, and indexed colors do not accept dynamic requests. Queries return rgb:rrrr/gggg/bbbb, or an empty value for dynamic colors and host-controlled selection styling without a fixed color override. See the Kitty specification.

Color stack

Kitty OSC 30001 ST pushes effective indexed and named colors, including dynamic cursor/selection behavior; OSC 30101 ST restores and removes the last entry. An empty semicolon is also accepted. Both commands require palette permission and emit no replies or color-scheme notifications.

The terminal-wide stack holds ten entries, dropping the oldest on overflow; an empty pop has no effect. Hard and soft reset clear it. Screen switches, resize, and host theme changes preserve snapshots. Pop restores saved effective color values while retaining the current host light/dark and bold-as-bright settings; subsequent color resets still use the latest host theme.

Color resets

OSC 104 restores the specified palette entries to the current host theme's configured values. Bare OSC 104 ST or OSC 104; ST restores all 256 entries; OSC 104;1;255 ST restores only entries 1 and 255. Decimal indices must be in 0..255. Invalid and empty fields in a nonempty list are ignored individually, duplicates are coalesced, and a list without valid indices changes nothing. Non-ASCII bytes reject the complete list.

OSC 110, 111, and 112 restore the theme's foreground, background, and cursor colors respectively. They accept no payload, with an optional trailing semicolon. These resets preserve other application overrides and host presentation preferences. They obey palette permission and emit no replies. See xterm's color operations.

Change reports

Both subscriptions are initially disabled, accept DECSET/DECRST, and are disabled by RIS or DECSTR. Terminal-response permission gates reports without changing subscription state; palette permission independently gates application color operations. Reports use the same ordered session output path as input and explicit replies.

Mode 2031 (CSI ?2031h / CSI ?2031l) subscribes to host theme palette changes. Reports are CSI ?997;1n for dark or CSI ?997;2n for light, matching the one-shot CSI ?996n query. Changed host palette values report even if the light/dark preference is unchanged. Enabling alone emits nothing, and application OSC color changes or resets emit no change reports. See the color-scheme protocol.

Mode 2048 (CSI ?2048h / CSI ?2048l) subscribes to text-area size changes. Every enable request, including repeated enable, immediately reports the current size as CSI 48;rows;columns;heightPixels;widthPixels t. Subsequent reports follow completed changes to grid dimensions or text-area pixels. Identical geometry emits nothing. Pixel dimensions exclude padding and are zero when unavailable. See the in-band resize protocol.

Mode status reports

DECRQM returns set (1), reset (2), permanently set (3), or unsupported (0). ANSI and DEC namespaces are independent.

Mode 3 reports the last DECCOLM selection, not measured window width. Mode 1048 is an action and reports unsupported. Standalone declares supported bell actions; IntelliJ does not. Requests accept one mode parameter; malformed, overflowing, cancelled, or incomplete requests receive no reply. Queries do not mutate state. See the mode reference for names.

CSI ?2027$p replies CSI ?2027;3$y: grapheme processing is always enabled. DECSET/DECRST 2027 leave that policy unchanged, including across RIS, DECSTR, screen switches, and resize. ANSI mode 2027 is unsupported. Replies use the normal terminal-response permission; no window permission is required. This advertises grapheme processing, not complete conformance to the original Unicode Core draft: KetraTerm retains its documented VS15/VS16 width policy and streaming placement.

Streaming grapheme placement

Printable prefixes are published at each parser call boundary. Segmentation continues across calls; retained continuations update the same cell with its original attributes. Core adjusts the following cursor and pending wrap.

Publication commits grid effects. Later width changes do not relocate the cluster, reverse completed wraps/scrolls/insert shifts, or restore overwritten text. Narrowing frees a spacer as blank; widening consumes a neighboring cell when it fits. At the right margin, text remains in the single available cell. A rejected initial write has no continuation target.

Whole-input and split-input placement can therefore differ at margins, over occupied cells, and on tiny grids. Retained text, cell integrity, and following text must still be preserved. See grapheme retention and verification.