DSH plugin cwd boundary: why completion is directory-scoped
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:
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:
ctx.fileReferences.list(agent, query, signal)— the abstract seam receives the agent directly;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:
| Workaround | Apparent effect | Real problem |
|---|---|---|
Join ../ in the frontend | Parent paths appear in the list | Outside discovery; tool calls fail |
| Make the provider scan the whole disk | More candidates | Out of bounds, slower, permission errors |
| Filter unrelated files in the UI | A cleaner list | Scope 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:
- Switch the working directory — move the session cwd to the target and request candidates again.
- Start a new session — launch in the target directory and leave the old session untouched.
- 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;
sameWorkspacesays 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:
| Scenario | Expected |
|---|---|
| Subdirectory session searches a parent file | No candidates |
| Same prefix after switching to the parent | Candidates appear |
| Existing file inside the same directory | Candidates 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
FAQ
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.
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.
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.
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
- DeepSeek Harness reference - Session references· deepseek-ai
- session-controller file-references.ts· deepseek-ai