dsh-tm-guard

dsh plugin --profile web add dsh-tm-guard

dsh-tm-guard

A zero-intervention permission gate for DeepSeek Harness (DSH) agents on macOS — active on install. Writes that can be undone via a local git baseline or macOS Time Machine are auto-approved and automatically snapshotted; network access, package installs, process/system management, and reads of sensitive credential paths are blocked; every decision is audited — the audit log keeps everything by default, with optional automatic cleanup of the oldest records.

Core rule: operations that can be rolled back are allowed; operations that cannot be rolled back are denied.

---

Quick Start (2 minutes)

1. Install: dsh plugin --profile <name> add dsh-tm-guard (see [Installation](#installation)).

2. Verify it loaded: boot the profile — the console prints [tm-guard] Loaded. Protected paths: ... (see [Verify the install](#verify-the-install)).

3. Protect your workspace: defaults already protect process.cwd(), deny network/system operations, and block reads of 12 sensitive credential paths. To protect more directories, add protectedPaths to your profile's cordis.patch.yml ([Configuration](#configuration)).

4. Unlock the tools you explicitly trust: subagent, workflow, web_search, web_fetch, skill, ... are DENIED by default (classified mixed/unknown). Add the ones you trust to extraAllowTools in your profile's cordis.patch.yml. ⚠️ Never add subagent / subagent_fork / workflow / job_output — the allow-list short-circuits the classifier (see [Limitations](#limitations--honest-scope)).

The two fields that change the experience most: protectedPaths (what the agent may write) and extraAllowTools (which tools bypass the gate). Everything else has a safe default.

What this is — and isn't

It is a DSH Cordis plugin / bundle: an npm package (dsh-tm-guard) that declares dsh.bundle.patch, hooks DSH's tools/pre-execute waterfall, registers tm_* model tools, and injects an operating-mode system-prompt section. It installs with the official dsh plugin add flow and runs inside the DSH host process with the host's permissions.

It is not:

• a Claude Code plugin (no Claude Code plugin manifest or Claude Code hooks),
• a VS Code extension,
• a standalone CLI or product,
• a security sandbox (see [Limitations & honest scope](#limitations--honest-scope)).

---

Prerequisites

• macOS with APFS. The plugin shells out to /usr/bin/tmutil and uses local APFS snapshots; there is no non-macOS support.
• Time Machine configured with a backup destination, and the workspace on a TM-backed volume that is not in Time Machine's exclusion list. Verify:

  tmutil destinationinfo
  tmutil listlocalsnapshots /

• Full Disk Access granted to the terminal/app that runs dsh (needed for browsable-backup restore and some tmutil operations), if you want automated rollback from completed backups. Local snapshot creation itself needs no sudo on normal user volumes.
• git on PATH for the primary instant rollback net (a local baseline is auto-created per writable directory; all git operations are local/offline).
• DSH CLI installed, matching the peer range in package.json — currently @deepseek-ai/cordis >=4.0.0 and @deepseek-ai/dsh-tools >=0.1.0-rc.1 <0.1.0 || >=0.1.0 <0.1.2-0 || >=0.1.2-0 <0.2.0-0 || >=0.2.0-0 <0.3.0-0 (covers dsh 0.1.x including 0.1.2-rc.1 and dsh 0.2.x including 0.2.0-rc.2).

---

Installation

A DSH profile installs out-of-tree bundles via dsh plugin --profile <name> ... (forwarded to pnpm inside the profile directory). Choose any profile name, e.g. web or a throwaway tm-lab.

From npm (recommended)

Prebuilt lib/ ships in the package, so no build step or build-script approval is needed:

dsh plugin --profile web add dsh-tm-guard

From GitHub / source

# pnpm >=10 blocks git-dependency build scripts until you allow them.
# The package's prepare script runs its zero-dependency build (see Development).
dsh plugin --profile web add github:ChaoJie0/dsh-tm-guard

If the install fails on the build-script approval, add the key pnpm prints to the profile's pnpm-workspace.yaml:

allowBuilds:
  dsh-tm-guard: true

and re-run the command. Treat that allowance as permission to run the package's code at install time on your machine; pin a commit when auditing supply chain: github:ChaoJie0/dsh-tm-guard#<sha>.

Local checkout (testing)

git clone <repo> dsh-tm-guard
cd dsh-tm-guard
npm install        # no runtime deps; runs prepare → builds lib/
dsh plugin --profile tm-lab add .
# or a packed tarball: npm pack → dsh plugin --profile tm-lab add ./dsh-tm-guard-<version>.tgz

Direct source overlay (development only)

Without installing, load the TypeScript source straight into a running DSH via the local overlay file (the path is machine-specific; this is the file shipped in the maintainer's checkout, not the bundle patch):

dsh web --patch "/abs/path/to/dsh-tm-guard/cordis.patch.local.yml"

---

Verify the install

# 1. The composed tree must contain a dsh-tm-guard layer with a tm-guard row:
dsh --profile tm-lab --dump-config | grep -A2 'dsh-tm-guard'
#   # == dsh-tm-guard
#   - id: tm-guard
#     name: dsh-tm-guard

# 2. Boot the profile — the console should print:
#   [tm-guard] Loaded. Protected paths: ... Audit log: ... Deny-read paths: ...
#   [tm-guard] 首次运行基线报告已生成: .tm-guard/baseline-report.md — 请查看你的实际保护等级
dsh --profile tm-lab

# 3. Read the first-run baseline report — what THIS machine actually protects:
cat .tm-guard/baseline-report.md

# 4. In a session, the registered tools are available — ask the agent to run
#    tm_status, or call tm_audit to inspect the gate log.

Remove cleanly with:

dsh plugin --profile tm-lab remove dsh-tm-guard

---

How it w

…(truncated)