ChatGPTClaudeGrok / X / CursorGemini

DSH plugin hand-typed mentions: text vs structured input

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnesssession referencementionstructured input
Pasting a mention from a doc sends a message but loads nothing. Why references is a separate input, what prepare deletes, and two honest host choices.

In DSH plugin, pasting a mention from a document produces a normal message with no referenced content, because the paste carries display text rather than a selection. The missing piece is not syntax; it is the absence of that session from references.

DeepSeek Harness: Why a pasted mention does nothing

Because the user copied display text, not a choice. (source) Scene:

text
Copied from docs: @[Fix login timeout](dsh-session:abc123)
Pasted into the input, sent
Result: the message goes out, but the referenced session is not loaded

The user assumes "the text contains a reference, so it must have been read". The chain is missing the crucial step: that session never entered references.

Text is for humans; references are for the program. They can coexist, but neither substitutes for the other.

DeepSeek Harness: references is a separate input

It is a prepare argument, not something derived from the body. (source) Structurally:

InputShapeRole
contentReadable content blocksWhat the user actually says
referencesStructured arrayWhich sessions to read
signalCancellation boundaryWhether this turn is still valid

Each entry in references is a SessionReferenceInput with an authoritative sessionId and an optional label.

Passing them separately means "what the body says" and "which sessions are read" are independent facts.

DeepSeek Harness: prepare removes tokens, it does not resolve them

It subtracts, it does not parse. (source) The official description of content is the readable content after host mention tokens are removed.

In practice:

  • prepare deletes mention markers from the body;
  • It never takes those characters and looks up sessions;
  • Every session to read comes from references.

This design avoids "the body is the instruction": the model sees clean text, while the read set is decided by structured input.

Expect prepare to be a fallback parser and you will observe "the text disappeared but the context never arrived".

DeepSeek Harness: Two honest host choices

Either parse it into a selection, or reject it clearly — never leave it ambiguous. (source) Two options:

  1. Parse before submit — recognize mentions in the input, convert them into SessionReferenceInput entries, and pass them in references.
  2. Do not support it — treat a hand-typed mention as plain text and tell the user to pick a session from the list.

The first is better UX but requires the host to parse, validate, and deduplicate. The second is simple but leaves users wondering why their paste does not work.

Whichever you choose, never highlight it in the UI without adding it to references. That makes users believe the reference worked.

A middle path is worth considering: allow the paste, then immediately convert it into a visible reference chip and write it into references. Habits stay intact and structured input survives.

DeepSeek Harness: The security value of explicit selection

Explicit selection makes "what was read" auditable. (source) Three benefits:

  1. Users know which session they chose instead of being led by a string;
  2. Permission checks can happen at selection time, before any text parsing;
  3. Logs record a list of session ids rather than a forgeable string.

The third matters most: text can be copied, edited, and concatenated; structured input cannot.

So "hand-typed mentions should just work" is not a convenience feature; it moves the trust boundary from a selection gesture to arbitrary text.

DeepSeek Harness: Verifying separation

Three steps confirm text and references stay apart. Steps:

  1. Put only a mention in the body with empty references and confirm no additionalContext;
  2. Put plain text in the body with one session in references and confirm context exists;
  3. Put a mention in the body and the same session in references and confirm context appears once.

Step 1 proves text does not trigger reads; step 2 proves reads depend only on references; step 3 confirms no duplicate aggregation.

Three passes mean the two pipelines are not entangled.

Do not stop at whether a chip appears in the UI — open the request and confirm references contains the session id. A chip can be decoration while the real reference lives in the structured field.

Storing a mention as plain text has another side effect: import and export pollute the body, and if a host later parses it again, that is a back door.

That closes the A list. Next comes preparation and governance: read the DSH plugin prepare contract; for candidates carrying mentions, read DSH plugin remote candidates; for the wider picture, read how DSH plugin implements session references.

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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

In DSH plugin, why does a pasted mention not load the referenced session?

Because the paste carries display text, not a DSH plugin selection. DSH plugin reads sessions only from references; without a SessionReferenceInput, prepare has nothing to fetch even if the text looks like a mention.

For DSH plugin, does prepare search the message body for mentions?

No, DSH plugin prepare never searches the body for mentions. It removes host mention tokens from readable content as a subtraction step and never resolves those characters back into sessions.

With DSH plugin, should a host support hand-typed mentions at all?

Either DSH plugin host choice is defensible: parse pasted mentions into references before submit, or explicitly reject them and ask users to pick from the list. Highlighting without adding a reference is the one unacceptable option.

In DSH plugin, what does explicit selection buy in security terms?

DSH plugin's explicit selection produces an auditable record of which sessions were read. Text can be copied, edited, or concatenated, while references carries authoritative session ids that logs and permission checks can trust.

Related Terms

references
references is the structured array telling prepare which sessions to read; it is not derived from message text.— DeepSeek Harness reference - Session references
SessionReferenceInput
SessionReferenceInput is one reference item with an authoritative sessionId and an optional label.— DeepSeek Harness reference - Session references
mention token
A mention token is the host's textual marker inside content, which prepare removes without resolving it.— session-reference/src/index.ts
explicit selection
Explicit selection means the user chooses a session in the UI, producing structured input rather than text to be parsed.— DeepSeek Harness reference - Session references

Sources