dsh-minimal-anchor

A DeepSeek Harness (dsh) plugin that shields turn 1 from tool-schema overload.

Why

A fresh dsh session hands the model the entire configured toolset — file edits, bash, subagents, jobs — on message one, even when the first message is just "look at this repo and tell me what's going on." A smaller, focused schema on that first turn keeps the model's early reasoning on exploration instead of premature action, without touching how any later turn behaves.

dsh-minimal-anchor hooks the harness's own prompt-assembly pipeline to:

1. Prune tools on turn 1 only — down to a configurable whitelist (default: read, glob, grep).
2. Prepend a short structural preamble on that same turn, framing the session as exploration-first.
3. Get out of the way from turn 2 onward — every later assembly for that session passes through completely untouched, full toolset restored.

Install

dsh plugin --profile <name> add dsh-minimal-anchor

or from a local checkout:

dsh plugin --profile <name> add /path/to/dsh-minimal-anchor

This adds the package as a dependency of the profile, but does not by itself activate it — dsh only applies a package's dsh.bundle patch for packages listed in that profile's dsh.profile.bundles. Add the package name to that list in profiles/<name>/package.json:

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "@deepseek-ai/dsh-headless",
        "dsh-minimal-anchor"
      ]
    }
  }
}

Confirm it composed with dsh --profile <name> --dump-config — you should see a minimal-anchor entry. (An equivalent alternative that skips the bundles list entirely: insert it directly in your own profiles/<name>/cordis.patch.yml — see Configuration.)

Usage

Nothing to invoke — it's a passive plugin. Boot your profile as usual (dsh web, dsh --profile headless "...", etc.) and the first turn of every new session goes out with the pruned tool list and preamble automatically.

Configuration

# profiles/<name>/cordis.patch.yml
- insert:
    - id: minimal-anchor
      name: 'dsh-minimal-anchor'
      config:
        whitelistedTools: [read, glob, grep]
        enforcePreamble: true
        customPreamble: 'Your own turn-1 framing text.'

Field	Default	Description
whitelistedTools	[read, glob, grep]	Tool names kept on turn 1. Must match the exact registered tool names in your profile — check dsh --profile <name> --dump-config if unsure, names differ from plugin to plugin.
enforcePreamble	true	Whether to prepend the structural preamble section on turn 1.
customPreamble	(built-in exploration-framing text)	Preamble text, used only when enforcePreamble is true.

Extending rather than replacing the default whitelist? DEFAULT_WHITELISTED_TOOLS and DEFAULT_PREAMBLE are exported from the package if you're composing config in TypeScript rather than YAML.

How it works

Hooks the system-prompt/assemble waterfall from @deepseek-ai/dsh-system-prompt, which runs once per turn and produces the PromptAssembly (sections, tools, contexts) actually sent to the model. A WeakSet keyed on the assembly's scope tracks whether that scope has assembled before; the first time, it filters assembly.tools to the whitelist and unshifts the preamble section, then calls next() so every other listener in the waterfall still runs normally. Every later assembly for that scope short-circuits straight to next() — no mutation, no persisted per-session state beyond the WeakSet entry, which needs no explicit teardown since it dies with the scope object.

There is no agent/request or per-message hook in the real harness — this plugin does not use one, unlike an earlier draft of this same idea that assumed events that don't exist in dsh.

Troubleshooting

Turn 1's tool list came back empty. whitelistedTools matches on the exact registered tool name — these differ per harness install and per other plugins you have active. Check the real names with dsh --profile <name> --dump-config, or open the Trajectory tab in the web UI for a session and look at the Tools panel on "Initial System Prompt". An early draft of this plugin shipped with guessed names (read_file, list_dir, search_files) that don't exist in the real harness — the whitelist silently matched nothing and pruned every tool.

Plugin doesn't seem to load / no minimal-anchor entry in --dump-config. Being a listed dependency of the profile (e.g. after dsh plugin add) is not enough — the package also needs to be in that profile's dsh.profile.bundles list (see Install) before its dsh.bundle patch gets applied.

Loader crashes with Cannot read properties of undefined (reading 'validate') on a fork. A Cordis plugin's exported Config must be a schemastery schema (z.object({...})), not a plain object — the loader calls .validate on whatever Config exports.

Development

npm install
npm run typecheck
npm test

Verified against a real local dsh boot (not just types): installed into a scratch profile, patched in, and run against a live model — the outbound request on turn 1 carried exactly the whitelisted tools and the preamble text, and turn 2 carried the full toolset with no preamble.

License

MIT