ChatGPTClaudeGrok / X / CursorGemini

DSH plugin cwd boundary: why completion is directory-scoped

Plugin DevelopmentPublished 2026-11-10Author: DeepSeek Plugin Market
DSH pluginDeepSeek Harnessfile referencecwdworking directory
File candidates only come from one working directory. Where cwd comes from, why three out-of-bounds workarounds fail, and three legitimate ways to change scope.

When completion cannot find a file, check whether the file is inside the session's cwd before suspecting the plugin. DSH plugin bounds discovery by the addressed agent's working directory; the frontend tree, the editor's open file, and your last browsing location do not participate.

DeepSeek Harness: A subdirectory session cannot see the repo root

This is the boundary working, not a missing feature. (source) A familiar scene:

text
repo root/
├── pnpm-workspace.yaml
└── packages/web/        <- session started here

The session runs in packages/web, the user types @pnpm, and candidates stay empty. The file exists, the provider did not miss it — discovery simply covers packages/web only.

The quick test: switch the session to the repo root and type the same prefix. If candidates appear, the boundary explained it; if they stay empty, then look at the provider.

An even faster check: type a file name that definitely exists in the current directory. If it appears, the pipeline works and only scope is in question — the plugin is not broken.

Where DSH plugin cwd comes from

cwd belongs to session context and comes from the addressed agent, not from a frontend directory. (source) Both entry points show it:

  1. ctx.fileReferences.list(agent, query, signal) — the abstract seam receives the agent directly;
  2. ctx.sessionFileReferences.list(...) — the remote adapter resolves the agent from the live Session identity.

The second explains "I switched folders in the UI and completion did not change": the live identity did not change, the resolved agent did not change, and neither did cwd.

That also means cwd is an input to discovery, not extra information sitting outside a security boundary. Any implementation that reads the filesystem directly while bypassing the agent has already left this pipeline.

In monorepos, each package may run its own session. The same file name is visible per session, so cross-package references look like "the other package clearly has it, but completion cannot find it". That is still the boundary, not a cache problem.

DeepSeek Harness: Three out-of-bounds workarounds that fail

Joining paths, recursive scanning, and frontend filtering all miss the point. (source) Comparison:

WorkaroundApparent effectReal problem
Join ../ in the frontendParent paths appear in the listOutside discovery; tool calls fail
Make the provider scan the whole diskMore candidatesOut of bounds, slower, permission errors
Filter unrelated files in the UIA cleaner listScope unchanged, problem only hidden

All three treat scope as a presentation issue. Scope is an interface contract, and only a cwd change moves it.

There is a hidden cost too: a path obtained out of bounds may point somewhere the user cannot access. It looks usable during completion and fails at execution, which is harder to diagnose.

DeepSeek Harness: Three legitimate ways to change scope

Switch the directory, start another session, or use another entry point. (source) Options:

  1. Switch the working directory — move the session cwd to the target and request candidates again.
  2. Start a new session — launch in the target directory and leave the old session untouched.
  3. Use a different entry point — a terminal and the web UI each keep their own session context and cannot substitute for each other.

The shared precondition is simple: make the agent's cwd the directory you want. There is no fourth option.

After switching, request candidates again instead of reusing the previous list; that list belongs to the old cwd.

If a product genuinely needs cross-directory references, the right design is an explicit "change working directory" action, not fabricated paths in the completion list.

DeepSeek Harness: How cwd and sameWorkspace fit together

One defines scope, the other answers a yes/no question; do not mix them. (source) Division of labor:

  • cwd decides what can be found;
  • sameWorkspace says whether the source session shares the requester's cwd, and is true only when cwd is recorded and equal.

In session reference UIs, hosts often want a "same project" badge. If the other side's cwd is unavailable, the host should not compare by itself; sameWorkspace exists for hosts that only need a distinguishing bit.

It is neither a permission check nor a path-equivalence check. Two path strings can look identical and still normalize differently, and that comparison does not belong in a frontend.

A test matrix for the DSH plugin cwd boundary

Three comparisons separate scope problems from provider problems. Matrix:

ScenarioExpected
Subdirectory session searches a parent fileNo candidates
Same prefix after switching to the parentCandidates appear
Existing file inside the same directoryCandidates appear, stable order

A failure in row one means the boundary is not enforced; row two means the switch did not reach the agent; only row three points at the provider or the query.

When testing, record the session's starting directory along with the result. Many false conclusions come from a test harness that already runs at the repo root, where the boundary appears to "not work".

With scope settled, the next step is input parsing. Read how the DSH plugin file reference query works; to combine several sources, read composing DSH plugin providers; for the wider picture, read how DSH plugin implements session references.

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

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Why can't a DSH plugin session started in a subdirectory see repo-root files?

DSH plugin bounds discovery by the addressed agent's cwd. DSH plugin produces candidates only inside that working directory, so a root file is out of scope until the session or working directory changes.

For DSH plugin, can a host type ../ in the frontend to reach a parent directory?

A host cannot reach a parent directory that way in DSH plugin. Candidate paths come from provider discovery, and a hand-built path is outside that range; even if it renders, later filesystem tool calls will reject it.

Is DSH plugin cwd sent by the frontend or recorded by the server?

DSH plugin cwd belongs to the session and agent context, not to a frontend tree selection. The remote adapter resolves the agent from the live Session identity, so switching folders in the UI does not widen completion.

In DSH plugin, can sameWorkspace replace comparing cwd?

DSH plugin's sameWorkspace only answers whether the cwd values match. DSH plugin allows cwd to be missing, so a host should not compare paths it never received; sameWorkspace exists for exactly that case.

Related Terms

cwd boundary
The cwd boundary is the upper limit of file reference discovery, set by the addressed agent's working directory.— DeepSeek Harness reference - Session references
agent
agent is the first parameter of the file reference interface; it supplies the working directory scope and determines affinity ordering.— DeepSeek Harness reference - Session references
Session identity
Session identity is the session identifier carried by a live request, which the remote adapter uses to resolve the target agent.— session-controller file-references.ts
working directory switch
A working directory switch changes the session cwd, and file reference discovery follows that change.— DeepSeek Harness reference - Session references

Sources