ChatGPTClaudeGrok / X / CursorGemini

DSH plugin file reference candidates: just path and kind

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessfile referenceFileReferenceCandidateplugin development
A file reference candidate carries only path and kind. Here's the cwd boundary, provider ordering, why discovery never reads content, and where reading fits.

A DSH plugin file reference candidate has exactly two fields, path and kind — not an oversight, but a split between discovery and reading: discovery answers which paths exist, and reading happens after the user picks one. The moment you stuff content into a candidate, you break keystroke latency, permission boundaries, and determinism at once.

What a DSH plugin file reference candidate contains

A candidate is a completion record, not a file object. (source) The official type has two fields:

FieldTypeMeaning
pathstringUser-visible path accepted by prompts and filesystem tools
kind'file' | 'directory'A directory keeps completion open; a file closes the mention

The comment on path is explicit: it is a path that is visible to users and accepted by both normal prompts and filesystem tools. In other words, it is a string that can be consumed again, not an open file handle.

kind describes interaction state, not a file-type verdict. Selecting a directory keeps the completion list open so the user can descend; selecting a file ends the mention. Insert a directory as a file and the user immediately notices that completion closed too early.

A typical flow looks like this: the user types @src, and candidates include src/ as a directory plus src.ts as a file. Pick the first and the input keeps @src/ while requesting more candidates; pick the second and the mention is complete. The host never has to decide whether a string is a directory — kind already says so.

One more detail: kind comes straight from a directory entry, without opening the file. That is why completion still works when a file is unreadable or a read would time out.

Why DSH plugin candidates carry no file content

Because discovery runs at keystroke rate, while reading content is expensive. (source) Candidates regenerate on every character; reading files each time makes input latency grow with directory size.

The cost has three layers:

  1. Latency — a workspace with thousands of files would read content on every keystroke, with unpredictable delays.
  2. Permissions — candidates may include paths the user cannot read; reading during discovery would fail the whole completion.
  3. Determinism — content changes between calls, so the same query returns different results and hosts cannot cache them.

So the contract keeps candidates minimal: path plus type. Any "while we are here, add a size or a summary" idea turns a lightweight lookup into a heavy scan.

A simple test decides whether a field belongs in a candidate: can it be derived from a directory entry alone? File name and directory status can; content, line counts, and summaries cannot, because they require opening the file.

The reverse also holds: if candidates truly depended on content, completion would fail wholesale in directories without read permission. In practice it keeps working, which confirms that only directory entries are consulted.

How cwd bounds DSH plugin discovery

The boundary comes from the addressed agent, not from the folder a frontend happens to display. (source) The first parameter of list(agent, query, signal) is the agent, and the official comment states that the target agent's session cwd constrains discovery.

Two consequences follow:

  • Switching the file tree in the UI does not widen candidates unless the agent's cwd changes;
  • Descending into a subdirectory works by selecting a kind: 'directory' candidate, not by making the server scan recursively.

If a session runs in a subdirectory but the user wants a parent file, the fix is to change the working directory or the session — not to type ../ in the host. A hand-built path may render, but it is outside the discovery boundary, and later tool calls will fail for the same reason.

This shows up most in monorepos: the session lives in packages/web, the user wants the root pnpm-workspace.yaml, and it never appears. Nothing is missing in the plugin; the boundary simply is packages/web. Move the session to the repository root and the candidate shows up.

Who owns ordering and namespaces in DSH plugin

Ordering and namespace access belong to providers; hosts only render. (source) The official description of FileReferenceService is precise: providers handle ordering and namespace access, and never read file content.

That division solves three recurring problems:

  1. Stable order — providers produce a deterministic sequence, and a host that re-sorts destroys it.
  2. Namespace collisions — when several sources contain files with the same name, the provider decides how to present them instead of a frontend deduplicating.
  3. Combined sources — a remote adapter sits above composed providers and exposes one outlet, so the host does not need to know how many sources exist.

A useful smell test: if host code sorts candidates by modification time or filters duplicate paths, that logic is in the wrong layer.

Where reading file content belongs in DSH plugin

After the user selects a candidate, read through filesystem tools instead of changing the candidate shape. (source) A workable order:

  1. A candidate returns path; the user clicks or presses enter.
  2. The host inserts the path into the draft or passes it as a tool argument.
  3. If a preview is needed, issue a separate read and handle permissions and size.
  4. A failed read affects only the preview, never the completion list.

The benefit is structural: discovery stays cheap, reading happens only when required, and failures do not empty the picker.

If a product genuinely needs summaries inside the list, that is a different capability and deserves a separate endpoint. Adding fields to FileReferenceCandidate changes a shared type for every host at once.

DeepSeek Harness: A five-point checklist for the candidate contract

Five checks that reveal boundary violations immediately. Checklist:

  1. Print one candidate and confirm it has only path and kind.
  2. Type five characters in a row and confirm identical query results keep identical order.
  3. In a subdirectory session, type @ and confirm parent files do not appear.
  4. Select a directory and confirm completion stays open; select a file and confirm it closes.
  5. In a directory without read permission, type @ and confirm file names still list.

Check five is the permission proof: candidates do not depend on content, so listing a directory needs no read access.

If all five pass, your implementation is still on the discovery layer. To wire reading next, read how the DSH plugin file reference query works; to choose a host adapter, read the two file reference services; for the wider picture, read how DSH plugin implements session references.

Sources: DeepSeek Harness reference - Session references, file-reference types.ts

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why does a DSH plugin file candidate not include the file content?

DSH plugin omits file content because candidates are regenerated at keystroke rate. DSH plugin keeps discovery to paths and types; attaching content would mean reading files on every character typed, which hurts latency, permissions, and determinism.

For DSH plugin, if FileReferenceCandidate has only two fields, where do file size and mtime come from?

File size and mtime sit outside the DSH plugin candidate contract. DSH plugin does not surface them during discovery. If a host needs them for a preview, read them after the user selects a path instead of extending the shared type.

Why does DSH plugin only complete files inside the current cwd?

DSH plugin bounds discovery by the addressed agent's session cwd. DSH plugin does not scan above that boundary. To reach parent files, switch the session or working directory and trigger candidates again.

Can a host re-sort DSH plugin file candidates by modification time?

A host should not re-sort DSH plugin candidates by modification time. DSH plugin requires deterministic candidates and assigns ordering to the provider. A second sort makes identical queries return different orders and breaks directory-first completion.

Related Terms

FileReferenceCandidate
FileReferenceCandidate is a discovery result containing only path and kind, used for completion lists and never carrying file content.— DeepSeek Harness reference - Session references
cwd
cwd is the addressed agent's working directory and the boundary within which file reference discovery produces candidates.— DeepSeek Harness reference - Session references
provider
A provider supplies file reference candidates, owns ordering and namespace access, and does not read file content.— DeepSeek Harness reference - Session references
deterministic candidates
Deterministic candidates return the same path set in the same order for the same query in the same environment, which lets hosts cache and test them.— DeepSeek Harness reference - Session references

Sources