dsh-preset-tool-guard
Per-preset tool visibility for DeepSeek Harness (dsh).
Mount it once at the host level. It watches agent/created, reads the preset that agent actually
composed, and applies the official ctx.tools.restrict() seam on that agent's own scope — so each
preset exposes only the tools it should, while the heavy providers stay mounted and untouched.
简体中文说明见 README.zh.md
The problem
dsh resolves tools along agent → preset → global. A preset composition mounts its own rows; it
does not restrict what is inherited from the global layer. So any plugin mounted at the host level
— a computer-use driver, browser MCP servers, image providers — shows up in the model's tool catalog of
every preset, including minimal ones that were designed to expose two or three tools.
Disabling those providers is not the answer: you lose the capabilities entirely, and it affects every
preset and session. The upstream discussion for the preset half of this is
deepseek-ai/deepseek-harness#5786.
ctx.tools.restrict({ allow, deny }) is the public, agent-scoped answer: a restriction masks what the
scope inherits (the global layer and every ancestor scope layer) and never what the scope registers
itself. This plugin wires that seam into the preset lifecycle.
What it changes
| Effect |
|---|
| Model-facing tool schemas (the per-request prefix) | the masked tools are gone |
| PTC mode SDK surface | gone as well (both projections read the same view) |
| Dispatch | masked calls return UNKNOWN_TOOL — a real mask, not a presentation filter |
| Other agents / presets | unaffected; a restriction is per scope |
| The provider itself | still mounted; every capability you kept keeps working |
Install
Requirements: Node ^22.19 or >=24 (see engines), and a harness that exposes
ToolRuntime.restrict() plus the agent/created event.
The package ships its own cordis.patch.yml, so installing it mounts the plugin row.
# any dsh CLI (TUI, web profile, …)
dsh plugin --profile <profile> add dsh-preset-tool-guard
# from GitHub
dsh plugin --profile <profile> add github:KouzakiUmi/dsh-preset-tool-guard
# from a local checkout
dsh plugin --profile <profile> add /path/to/dsh-preset-tool-guard
DSH Desktop has no dsh on PATH. The GUI executable is the Electron shell, not the CLI — passing
plugin … to it does not run a plugin command. Use the terminal shim that the desktop ships
(verified on DSH Desktop 2.0.17-next, core 0.2.0-rc.2):
$env:ELECTRON_RUN_AS_NODE = '1'
& "C:\Program Files\DSH NEXT\DSH NEXT.exe" --expose-internals `
"C:\Program Files\DSH NEXT\resources\app\lib\desktop-cli.js" `
plugin --profile desktop add dsh-preset-tool-guard
Both forms end up in pnpm inside the profile directory (plugin forwards its arguments to pnpm), so
add / remove / install all behave as you expect. Note that --profile is mandatory, and that the
bundled dsh refuses to boot a profile literally named desktop outside the Electron path.
Then restart DSH: the plugin is a host-side bundle, so the running process keeps its old tree.
On load, the plugin also sweeps existing agents returned by agents.list() and applies their rules.
To remove it, run the same command with remove, and delete the preset-tool-guard entry from your
profile patch (see below). Removing the package row alone leaves a dangling config block.
The npm package is dsh-preset-tool-guard; use dsh-preset-tool-guard@0.1.2 to pin this release.
Configure
The plugin's own patch ships a conservative default (dryRun: true, no allowlists). Put the real
configuration in your profile's cordis.patch.yml. Loader config for the same entry id is replaced
wholesale, so restate every field you care about — including dryRun, which otherwise falls back to
the code default false (masking enabled).
- id: preset-tool-guard
config:
allowlists:
minimal: [bash, pwsh, str_replace_editor]
standard: [read, write, edit, glob, grep, pwsh, skill, todo_write, web_search, memory_recall]
text: [read, write, edit, glob, grep, pwsh, grok_imagine_edit]
deny: []
denyPrefixes: []
groups: {}
disableGroups: []
skipUncomposed: true
report: true
# reportFile may be omitted (defaults to $DSH_HOME/logs/preset-tool-guard.log).
# A leading `~` is expanded; an absolute path is used as-is.
reportFile: C:/Users/you/.dsh/logs/preset-tool-guard.log
dryRun: false
| Field | Default in code | Meaning |
|---|
allowlists | {} | { presetId: [toolName, …] }. A matching preset keeps only the listed inherited tools; every other inherited tool is masked (fail-closed: a tool registered later on an inherited layer is not admitted, because the filter is a snapshot). An empty array or a list with no restrictable matches skips only the allowlist with a warning; the inherited tool surface is not cleared, and bottom rules still apply. Presets absent from this map get no allowlist, but still receive the deny / group rules below. |
deny | [] | Exact tool names removed from every agent, composed preset or not. |
denyPrefixes | [] | Plain startsWith prefixes removed from every agent (e.g. cua_driver_native__). |
groups | {} | Named groups: { groupId: { names: […], prefix: "…" } }. |
disableGroups | [] | Group ids whose members are removed from every agent. |
skipUncomposed | true | Skip the allowlist for agents with no composed preset. The deny / group half still applies to them. |
report | true | One report line per (re)application. |
reportFile | $DSH_HOME/logs/preset-tool-guard.log | Append reports here. false or "" disables file output. ~ is expanded; omit the field to use the default. |
dryRun | false | Measure and report only; change nothing. Start here when tuning. |
How it works
- The restriction is applied on
agent.ctx — the agent's own scope. restrict() derives the scope
from the calling context and refuses to run from a plain (unscoped) one.
- The filter is snapshotted at registration.
allow therefore keeps admitting only the names it
listed at that moment; a name that appears later on an inherited layer is not admitted. If you
need a late-registering provider to be visible, create a new agent after it registers.
- For that reason an allowlist match installs its mask even when nothing is currently excluded —
that is what keeps future inherited tools out. Skipping the install would silently turn a fail-closed
policy into a fail-open one.
- Names are resolved against the scope's restrictable set before the call: a name the agent cannot
see is skipped (never thrown), so a provider upgrade that renames a tool degrades to a smaller saving
plus a report note, not to a startable-but-broken deployment.
ToolRuntime.view() is not part of the documented Service contract. The plugin probes it and, if it
is unavailable, skips masking and says so rather than falling back to schemas() — the two sets
differ (schemas include the agent's own layer and the reserved transport name), and feeding those
names to restrict() would make the whole call fail.- The reserved PTC transport
run_code is never written into a filter.
- An allowlist with no restrictable matches is skipped with a warning;
deny, prefixes and disabled
groups still apply. An empty allowlist therefore does not clear the inherited tool surface.
- Late registrations receive bottom rules. The plugin listens to
tools/change and adds denials
for newly matching inherited names, including providers connected after agent creation. It does
not rebuild the allowlist snapshot or admit late allowlisted names. Repeated events add no duplicate
denials. Dry run reports these names without installing restrictions.
- Every failure path logs and returns; agent creation is never blocked.
- Preset switches are handled. Upstream
recompose (used when a blank session changes preset) only
rebinds the mount — it does not re-emit agent/created. The plugin listens for
agent-preset/selected, releases the previous restriction and re-applies, because restrictions
intersect and cannot be widened in place.
- The mask has plugin ownership too.
restrict()'s disposer is kept per agent and released when the
agent is disposed and when the plugin itself unloads, so a config reload cannot leave a stale mask
behind on a live agent.
Reporting
2026-10-04T12:34:56.789Z preset-tool-guard: excluded 114/168 inherited names (155810 of 199433 utf8 schema bytes, 78.1%, ~43281 tokens) agent="session-…" preset="standard" mode=allowlist
excluded / would exclude (the latter under dryRun), and mode=allowlist|bottom.- Counts and sizes describe the inherited surface: names the restriction excludes out of the names
the scope could restrict. Visible-tool counts can differ (see the two exceptions below).
- Sizes are UTF-8 bytes of the serialized schema, converted to a rough token estimate at 3.6 bytes per
token — a magnitude, not a tokenizer measurement.
- On a no-op it prints
无需掩码 / no mask needed instead.
- The same line is appended to
reportFile with an ISO timestamp. The host logger's output channel is
not necessarily a readable log file, so the file is the reliable record.
Measured on a desktop profile (core 0.2.0-rc.2): standard went from roughly 60K tokens of tool
prefix to about 10.5K of schema, with a computer-use driver (62 tools), two browser MCP servers (55
tools) and image providers excluded from the everyday presets — and still fully available in a full
preset that simply declares no allowlist.
Two ways a name stays visible
restrict masks only what a scope inherits. Two consequences are worth knowing before you file a
bug:
- Self-layer registrations. Tools a plugin registers on the agent's own layer are outside the
filter. On one machine
subagent, list_subagent_models, schedule_* and cordis_inspect_*
behave this way: they stay visible no matter what the allowlist says. An allowlist cannot remove
them — turn such a tool off in its own plugin's configuration.
- Not registered at that moment. A name whose provider is not connected, or not yet mounted when
the agent is created, is skipped. Keeping it in the allowlist does not reserve visibility for
later either (see the snapshot rule above); it only avoids a name-collision error.
The report line separates the two cases so you can tell them apart without guessing.
Development
npm test
node scripts/check-manifest.mjs
node scripts/check-patch.cjs [profileDir] [toolsJson] [--strict]
Defaults: profileDir = $DSH_HOME/profiles/desktop, toolsJson =
$DSH_HOME/tmp-guard-tools.json. It parses your profile patch with the !!js tag supported, prints
every preset-* declaration and the per-preset allowlist sizes, and — when the tool catalog file
exists — reports allowlist names the catalog does not contain.
The catalog file accepts either shape, so a raw cordis_inspect_query result can be written to disk
as-is:
{ "tools": [ { "name": "read", … }, … ] } (host / Tool / listTools output)[ "read", "write", … ]
Exit code is 0 on success and 1 on a parse failure, a structurally invalid patch, an unrecognizable
catalog shape, or (with --strict) a missing tool name. Without --strict, missing names are warnings
— names can legitimately be absent on another platform (the shipped bash row is Windows-disabled).
Compatibility
Verified on @deepseek-ai/dsh-* 0.2.0-rc.2 (Node ^22.19 || >=24). The plugin reads tools,
agentPresets and agents through ctx.get() at runtime and imports nothing at load time except Node
builtins, so the peer surface is small: @deepseek-ai/cordis (~4.x) plus a harness exposing
ToolRuntime.restrict(), agent/created, agent-preset/selected and tools/change.
Hosts without tools/change cannot update bottom rules for late registrations; existing rules still
apply when an agent is created or its preset changes. This is a visibility mask for inherited tools,
not a sandbox or a way to block tools registered directly on the agent's own layer.
License
MIT — see LICENSE.
