ChatGPTClaudeGrok / X / CursorGemini

DSH plugin label escaping: one bracket breaks a mention

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referenceescapinglabel
A ] in a session title ends a hand-built mention early. How label-safe JSON serialization fixes it, what hosts must not trim or replace, and a six-case matrix.

One ] in a session title ends a hand-built mention early — not an edge case, but the inevitable result of placing a label inside @[...]. DSH plugin solves it with label-safe JSON serialization; the host's job is to stay out of the way.

DeepSeek Harness: One bracket breaks the mention

Start with a hand-built failure. (source) Suppose the title is:

text
Fix [payment] callback

Hand-building produces:

text
@[Fix [payment] callback](dsh-session:xxxx)

The parser ends the label at the first ] and the remainder becomes unrecognizable text. The reference fails, and the user sees odd characters in the input.

The title is not invalid; the concatenation treated it as syntax.

DeepSeek Harness: What label-safe JSON means

It is a serialization rule with one goal: let arbitrary label text enter the bracketed structure safely. (source) The official material lists it alongside byte preservation as part of the session reference contract.

It resolves delimiter collisions specifically:

Label contentHand-built riskAfter serialization
Fix [payment] callbackTruncated at ]Preserved whole
review (v2)Parentheses read as URI boundsPreserved whole
a"bQuote breaks the structurePreserved whole

It is neither URL encoding nor HTML escaping. It serves mention syntax, not network transport.

DeepSeek Harness: Three escaping layers

Each layer handles one segment; do not mix them. (source) Division:

  1. Label layer — resolves conflicts between label text and brackets;
  2. URI layer — encodes the identity portion;
  3. Content layer — prepare removes tokens without rewriting other bytes.

A host normally touches only the output of layer one, the ready-made mention on a candidate. Layers two and three live inside the service.

Understanding the split tells you who to call when something breaks: wrong label display points at serialization, wrong target points at the URI, rewritten content points at the content layer.

DeepSeek Harness: Two rewrites hosts should avoid

Trim and replace: two harmless-looking actions. (source) Comparison:

ActionIntentConsequence
mention.trim()Remove edge whitespaceLabel changes; display differs across clients
Swapping ] for a full-width bracketMake it look nicerCharacters no longer match parser expectations

Both share one pattern: editing data for presentation. Presentation belongs to the render layer — extract the label and display it, rather than mutating the mention.

If a shorter display is needed, render the list from displayTitle or label; use the mention only when inserting.

DeepSeek Harness: How escaping relates to byte preservation

One guards structure, one guards content; both mean "do not change the meaning". (source) Relationship:

  • Label-safe JSON keeps a label from breaking the mention structure;
  • Byte preservation keeps prepare from rewriting the rest of the referenced content;
  • Neither permits a host to inject its own encoding rules.

So "normalize first, insert later" violates both: it can break structure and change bytes.

The correct boundary: the service serializes and reads; the host moves text verbatim and renders it.

DeepSeek Harness: A six-character test matrix

Six classes of characters in one pass. Matrix:

Title contentExpected
a]bMention structure stays intact
a(b)cURI boundaries do not shift
a"b'cQuotes do not affect parsing
Chinese titlePreserved unchanged
Emoji titlePreserved unchanged
Leading or trailing spacesSpaces kept, not trimmed

The last row is the easiest to overlook: spaces are part of the label, and removing them edits the user's title.

Do not stop at "it parses"; also assert that the resolved sessionId matches the candidate. Parsing into the wrong session is worse than failing.

With escaping covered, the next topic is hand-typed mentions. Read DSH plugin hand-typed mentions; for URI structure, read how DSH plugin parses a dsh-session URI; for the wider picture, read how DSH plugin implements session references.

Sources: DeepSeek Harness reference - Session references, session-reference/src/types.ts

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, why does a session title with a bracket break the mention?

Because the label sits inside DSH plugin's @[...] mention structure. A hand-built mention ends at the first ], so the rest becomes unparseable. DSH plugin handles this with label-safe JSON serialization.

For DSH plugin, is label-safe JSON just URL encoding?

No, DSH plugin's label-safe JSON is not URL encoding. It serves the mention's syntax structure, not network transport, and it is distinct from HTML escaping as well. The URI portion has its own encoding rules.

With DSH plugin, is it safe to trim a mention before inserting it?

No, trimming a DSH plugin mention is not safe. Trimming changes label content, and leading or trailing spaces are part of the title. Insert the mention verbatim and render the label separately if you need cleaner display.

In DSH plugin, what should a test assert beyond 'it parses'?

A DSH plugin test should assert that the resolved sessionId equals the candidate id. Parsing successfully while resolving the wrong session is the more dangerous failure.

Related Terms

label-safe JSON
Label-safe JSON is the serialization rule that lets arbitrary label text enter the bracketed mention structure without breaking it.— DeepSeek Harness reference - Session references
byte preservation
Byte preservation forbids rewriting referenced content beyond removing host mention tokens.— DeepSeek Harness reference - Session references
URI encoding
URI encoding handles the identity portion of the mention, separately from label serialization.— session-reference/src/types.ts
display rewrite
A display rewrite changes data for appearance, such as trimming a mention or swapping brackets, and breaks parsing assumptions.— DeepSeek Harness reference - Session references

Sources