dsh-coding-tools

A DeepSeek Harness host plugin with a narrowly scoped Settings card that adds compact, bounded coding tools without modifying DSH:

• code_read — UTF-8 code windows with exact-byte version tokens
• edit_ranges — atomic, observed-range edits with operator-configurable approval
• ast_grep — pinned ast-grep CLI over one provider-read file snapshot, with pagination and read-only process confinement
• lsp — persistent read-only language-server queries with bounded JSON-RPC
• Fresh diagnostic summaries after plugin-owned edits when the matching LSP server is already active

ast_edit and DAP debugging are deliberately not registered in the secure initial release. The browser bundle is limited to the Coding tools Settings card.

Requirements

• Node.js 22.19+ or 24+
• DeepSeek Harness 0.1.1-rc.2 or compatible public service contracts
• A DSH profile that supplies tools, fs, sandboxPolicy, sandbox, approval, spillStore, subprocess, and settings (the stock Web profile does)
• Optional absolute-path language server executables configured by the profile operator

Install

Build a local checkout, then enroll it in a DSH profile with the supported profile command:

pnpm install
pnpm check
dsh plugin --profile web add "C:\absolute\path\to\dsh-coding-tools"

The package contributes cordis.patch.yml, which inserts the package-prefixed row dsh-coding-tools. Restart the Web profile after host plugin changes. A raw source patch alone is not package enrollment.

For a published or Git install, pin a release or commit instead of a floating branch.

Configuration

An expandable Coding tools card appears in Settings → Plugins → Plugin configuration. It provides switches for code_read, edit_ranges, ast_grep, and lsp, separate Require edit approval and Require process-start approval controls, and a conspicuously warned native-Windows compatibility opt-in for reduced process isolation. Approval prompts default on. Advanced limits and language-server plans remain profile configuration. Saved settings persist in DSH's user layer and apply live: disabled tools are unregistered, enabled tools are registered, and process-backed resources are stopped or recreated without restarting DSH Web. Reconfiguration cancels in-flight reads and queries, drains edits that may already have committed, and invalidates existing cursors and code_read version tokens.

Profile patch layers can replace the inserted row with explicit base configuration:

- insert:
    - id: dsh-coding-tools
      name: 'dsh-coding-tools'
      config:
        inlineMaxBytes: 8192
        approvals:
          editRanges: true
          processStart: true
        processPolicy:
          allowWindowsPartialReadOnlyProcessConfinement: false
        codeRead:
          enabled: true
          defaultLines: 200
          maxLines: 2000
          maxBytes: 262144
          maxFileBytes: 16777216
          snapshotMaxBytes: 67108864
        versionedEdit:
          enabled: true
          requireObservedRanges: true
          maxOperations: 100
          maxChangedBytes: 1048576
          diagnosticsOnWrite: true
        ast:
          grepEnabled: true
          executable: '' # empty = pinned @ast-grep/cli binary
          maxFileBytes: 2097152
          maxMatchesPerPage: 50
          maxTotalMatches: 5000
          timeoutMs: 30000
        lsp:
          enabled: true
          servers:
            clangd:
              command: '/absolute/path/to/clangd'
              args: ['--background-index=false']
              extensions: ['.c', '.cc', '.cpp', '.h', '.hpp']
              languageId: 'cpp'
              env: {}
          maxOpenDocuments: 64
          maxDocumentBytes: 16777216
          maxDiagnosticBytes: 4194304
        debug:
          enabled: false

Executable paths in configuration must be absolute. Repository files never select a binary or inject command-line arguments. Environment entries are explicit; DSH's subprocess provider removes ambient credential-shaped and DSH_* variables before applying them.

See Configuration reference.

Native Windows compatibility

processPolicy.allowWindowsPartialReadOnlyProcessConfinement defaults to false. When explicitly enabled on native Windows, only ast_grep and configured LSP starts may accept DSH's partial restricted-token enforcement; full remains required on every other host and for every unknown enforcement value. The process policy is still forced to read-only, executable plans remain operator-controlled, and all normal bounds and lifecycle cleanup remain active.

This is reduced isolation, not an equivalent Windows implementation of Linux full confinement. Everyone-writable ACLs and NTFS hard links can weaken write isolation, FAT-class targets outside granted roots remain writable, and the backend does not isolate reads, network access, or process visibility. Use it only with trusted repositories and executables.

Tool workflow

Exact reads and edits

1. Call code_read with file, and optional one-indexed offset / limit.
2. Retain the returned version.
3. Call edit_ranges with that exact file, version, and non-overlapping operations.
4. Under a read-only session, retry the denied call once with sandbox_permissions: workspace-write and a sentence in justification; sandbox escalation always requires its own one-call approval. Under an already-writable session, the ordinary mutation prompt is required only when approvals.editRanges is enabled.

Disabling ordinary edit approval does not widen sandbox policy. The standard DSH escalation fields do, for one call only, and always retain approval; they are advertised only when the mounted filesystem reports sandbox enforcement. A bare filesystem cannot escalate and fails closed under read-only policy. Source-changing operations must refer only to complete lines present in the canonical byte-bounded code_read result for the same owner, canonical target, and exact version. Oversized lines may be reported with an explicitly unobserved preview and continuation offset, but are never authorized for mutation. Because the public host observation event is whole-target rather than range-aware, the plugin publishes it only after accumulated same-version code_read pages visibly cover the complete file; paginate to complete coverage before editing. append is the sole observed-range exception, but still requires an observed version. All operations validate before one provider-version-guarded atomic write.

Line operation semantics:

• replace: replace inclusive whole lines and preserve the following line separator
• delete: remove inclusive whole lines
• insert_before / insert_after: insert line-shaped text using the file's dominant separator
• append: append text, adding one dominant separator when the file lacks a final separator

BOM, existing untouched line endings, and UTF-8 bytes are preserved. Invalid UTF-8 and NUL-bearing binary files fail closed. Complete-file read limits are separate from returned-result limits. Successful publication always returns applied: true; intendedVersion is always identified, while newVersion is present only after a verified landed read. landedExact and postWriteWarning make any post-commit verification or diagnostic problem explicit so callers do not retry a committed write blindly. Diff previews and the complete structured result are UTF-8-byte bounded, with explicit sizes, truncation reasons, and a spill locator when available.

Structural search

ast_grep accepts a pattern, exactly one regular workspace file in paths, a required language, optional strictness, a page limit, and an owner-scoped cursor. Before launch it:

• resolves the file through ctx.fs and proves canonical workspace containment
• rejects explicit symlinks and directories
• performs a stable, byte-bounded provider read
• passes that immutable snapshot to ast-grep over stdin, never as a process path
• enforces result, capture, cursor, output, and time caps
• asks once for that process launch when approvals.processStart is enabled and forces read-only DSH policy; full enforcement remains mandatory unless a trusted operator explicitly enables the native-Windows partial-confinement fallback

Broad directory scans are deliberately gated off. DSH does not currently expose an atomic process read-whitelist/open-handle contract, so passing workspace paths to a later process would leave a read-side TOCTOU race. Completed records retained from lossy bounded output may still be returned safely. Matches and parse errors are deduplicated, deterministically sorted, capped, and paged by both item count and rendered/structured UTF-8 bytes. Incomplete coverage is reported with explicit counts, byte ceilings, limitReasons, and bounded parseErrors.

Language servers

lsp supports hover, definition, references, symbols, and diagnostics. A configured server starts lazily, requesting one-shot approval when approvals.processStart is enabled, remains scoped to owner + canonical workspace + profile, and stops on idle timeout or plugin disposal.

The client advertises no edit or command capability. Server requests for workspace/applyEdit are explicitly rejected; dynamic capabilities, terminal launch, workspace commands, and unknown server requests never execute. Results outside the session workspace are discarded.

Every file-backed action synchronizes the complete stable UTF-8 document under lsp.maxDocumentBytes; a source prefix is never presented as a complete document. LSP source limits are independent from code_read result limits. Positions are checked against the exact synchronized UTF-16 line, and a supplied file is synchronized before workspace-symbol queries.

Definitions, references, symbols, and diagnostics are normalized, deduplicated, deterministically sorted, capped, and paged by both item count and rendered/structured UTF-8 bytes. Counts identify duplicates, invalid or outside-workspace entries, omitted items, source bytes, and concrete limit reasons. Diagnostics are marked fresh only when a server-supplied version corresponds to the current synchronized document version. Versionless diagnostics are never certified as fresh; they may be returned as stale evidence with incomplete coverage. Diagnostic retention is deduplicated and ordered deterministically with explicit item, byte, and serialization-loss causes.

Security

Read Security model and Public contract matrix. Approval prompts are enabled by default. An operator may explicitly disable ordinary edit and process-start prompts independently; exact-version observation, atomic provider writes, absolute executable plans, bounded execution, and forced read-only process policy remain mandatory. Full confinement is the default requirement. Native Windows may accept DSH-reported partial enforcement only when processPolicy.allowWindowsPartialReadOnlyProcessConfinement is explicitly enabled. Sandbox escalation approval is never bypassed.

Development

pnpm install
pnpm typecheck
pnpm test
pnpm build
pnpm pack --dry-run

This repository is independent from the DSH source checkout. Never patch DSH to mount it.