Gates and a ledger for coding agents: denies writes to source files that were not read in this session, or that changed after they were read; records every write and verification with the real exit code; keeps the tests that failed before a fix visible until that same set passes; and flags source files changed by shell commands that were never declared. Its HTTP routes have no DSH access check, so a web page open in your browser could call them.
Install
# from GitHub (first run asks for allowBuilds approval — follow the hint, retry)
dsh plugin --profile web add github:ACAneSe1/dsh-work-guard
Any plugin you install runs third-party code with your own permissions — it can read your files, use your credentials, and reach the network, and tool approvals don’t sandbox it. GitHub-sourced plugins also run build scripts at install time — pnpm blocks those until you allow them, so an install can stop with ERR_PNPM_GIT_DEP_PREPARE_NOT_ALLOWED or ERR_PNPM_IGNORED_BUILDS; dsh prints the exact key to add under allowBuilds in your profile’s pnpm-workspace.yaml, and the install works on the next run. Allowing a build is a trust decision: only install sources you trust, and pin a commit (github:owner/repo#sha).
README
Turn "I fixed it" into evidence you can check.
English · 中文
Not advice to the model — four gates and one ledger: a file you never read cannot be written; a failed verification is never recorded as a pass; the tests that were red must go green before the work counts as done. Honest scope: the plugin itself has only been installed and run on Windows + DSH Desktop. The test suite runs on Linux and Windows (Node 22 / 24) in CI; macOS and headless profiles are unverified.
Three things you have probably seen
- "Fixed" — and the tests were never run.
- Tests red, report green. (an empty suite, or a failure recorded as success)
- The wrong place edited. A file judged without reading it, or the first ten lines read and line five hundred changed.
This plugin speaks at exactly three moments:
| Question | Its answer |
|---|---|
| Was this file read? | Not read → write denied |
| You said "verified" — what was the exit code? | No exit code → recorded as unknown, not a pass |
| Are the previously-red tests green now? | Not green → the panel stays red and names them |
Mechanisms, not suggestions
| Mechanism | What it does |
|---|---|
| Read before write | write / edit on a source file that was not read in this session is denied. |
| Read freshness | Denied when the file changed after you read it (2 s clock-skew tolerance). |
| Read depth | Denied when the edited lines fall outside the ranges you actually read; replacing a file wholesale needs a full read. |
| Real verification | work_verify runs the project's check and returns a few lines; the exit code is taken by the tool itself, never from a shell pipe. |
| Red → green | Failing test names come from the output or the JUnit XML; the same tests must turn green. |
| Script declarations | Shell writes are not blocked, but anything not declared with work_declare stays visible as unaccounted work. |
| Change ledger | Every write, every verification (exit code + failing names), every denial and every bypass goes into one JSONL. |
| Prompt section | Nine habits plus two self-check questions, injected through systemPrompt.section, so they arrive with every request. |
| UI | One small button in the composer (pending items + history) and one status line under it: say something when there is something to say, otherwise just "no pending items". |
| One code-health rule | remember { derivedStateOf { … } } — a keyless remember around derivedStateOf never recomputes. Denied at write time. Kotlin-only. |
Why this exists
The trigger, quoted from the person this was built for:
"When you chase a bug, review the code first — don't guess at the problem and then cover it with another pile of code."
Everything here comes from that sentence. In one day, the same three failures repeated:
- Guessing instead of reading. A file's text was judged from its shape; the "fix" removed a design the user had asked for. No measurement, no question.
- Covering the symptom. The bug lived in one line; the patch added code somewhere else so the symptom stopped showing.
- Claiming success without evidence. "Fixed" was said after an edit, before any build.
None of those are solved by a better prompt. They are solved by moving the cost to the moment of writing: if the file was not read, the write does not happen.
What it does not do
- It cannot block shell writes.
pwsh/bashdo not go through the tool layer; whether they can write is a session-permission question, not a plugin question. The guard records them instead of pretending to stop them. The ledger numberbypassis how that shows up. - It does not judge quality. It knows whether a file was read and whether a build ran, not whether the change is correct.
- No project paths are hardcoded; project roots are discovered from the files actually edited, and rules can be language-scoped. The built-in Kotlin/Compose rule runs only in Kotlin projects; the three read rules apply everywhere.
Install
npm pack # produces dsh-work-guard-<version>.tgz
# then, in the harness:
# plugin_manager install_bundle <absolute path to the tgz>
Requires DSH >=0.2.2-rc.1 <0.4.0-0.
The plugin registers one HTTP route (/work-guard/status), one tool (work_ledger), one prompt
section, and one client slot (conversation.composer.dock). Removing the bundle removes all of them.
Data
Everything lives in <DSH_PROFILE_DIR>/data/, or ~/.dsh/data/ when that variable is not set
(the Desktop host does not set it) — never in your repository:
work-ledger.jsonl one row per write/edit/verify/bypass/note
work-guard-state.json files read in the last 24h (so a restart doesn't force re-reading)
work-guard.config.json optional configuration
Ledger rows (v: 2):
{"v":2,"ts":1794656070764,"day":"2026-11-14","t":"18:32","kind":"edit","file":"src/a.ts","lines":12}
{"v":2,"ts":...,"kind":"verify","cmd":"./gradlew :app:assembleDebug"}
{"v":2,"ts":...,"kind":"bypass","file":"src/b.ts","cmd":"python patch.py"}
{"v":2,"ts":...,"kind":"note","note":"why this change was made"}
Old rows without ts are read as UTC (that is what the previous version wrote); new rows carry
milliseconds and a local-time day/clock for display only.
Configuration (optional)
<profile>/data/work-guard.config.json, merged over defaults:
{
"version": 1,
"prompt": "…",
"sourceExtensions": [".ts", ".kt"],
"verifyPattern": "gradlew|npm test|cargo (build|test)|go test|pytest",
"ledger": { "path": "", "rotateAtRows": 5000 },
"state": { "readTtlHours": 24 },
"projectMarkers": ["package.json", ".git"],
"rules": {
"read-before-write": true,
"read-freshness": true,
"read-depth": true,
"no-unkeyed-derived-state": true
}
}
Precedence: environment (DSH_WORK_GUARD_PROMPT, DSH_WORK_GUARD_LEDGER) → file → defaults.
A broken file falls back to defaults; /work-guard/status reports configSource.
Adding a rule
A rule is an object; the gate is a registry:
// lib/rules/no-platform-in-core.js
export const id = 'no-platform-in-core'
export const stage = 'pre-write'
export const applies = ctx => ctx.filePath.includes('/core/')
export function check(ctx) {
return /android\.|process\.platform/u.test(ctx.afterText ?? '')
? { deny: id, reason: 'core must not know about platforms' }
: null
}
Register it once (registerRule(rule)) — gate() does not change.
Escape hatch
// work-guard: allow exempts a line from the derivedStateOf rule.
There is no escape from read-before-write: read the file.
Tests
npm test # 等价于 node --test
162 cases: path identity, project-root discovery, local-time compatibility, ledger rotation, config merging, state TTL, rule registry, and the gate's deny/allow behaviour.
Known limits
- Path identity is an absolute normalised key (
keyOf). The old three-segment-tail matching was removed in 0.3: it let two same-named files in different projects unlock each other. A relative path is resolved against known project roots first; when it cannot be resolved the write is denied (fail-closed). - Bypass scanning walks the repository on shell calls, capped at 200 hits and depth 16.
- Configuration changes need a restart (no hot reload).
- Web / Desktop only.
webServeris a hard dependency (the status route lives there), so in a headless or SDK profile the plugin does not activate at all. /work-guard/statushas no authentication; it answers any local process.recent[]is reduced to file names and contains no command text.readnow records the covered line ranges; an edit outside them is denied. What still cannot be checked is whether the read was understood — the guard verifies exposure, not comprehension.- Only installed and run on Windows. The suite passes on
ubuntu-latestandwindows-latest(Node 22 / 24, four jobs green in CI), but the plugin has never been registered inside a DSH on Linux or macOS — macOS has no evidence at all. - Ledger rotation and the config file are not on a real-session path, but
tools/verify-extra.mjsexercises them for real (it builds a 5 000-row ledger to trigger rotation, and writes a config then re-reads it in a fresh process).
License
MIT
Links
More in this category
loopx-project/loopx#dsh-loopx-plugin★ 6694
LoopX, a provider-neutral, local-first state kernel and control plane for long-horizon agents: keeps Goal, Todo, gate, evidence, quota, recovery, and handoff state above DeepSeek Harness, while the plugin bootstraps the CLI and skills, admits bounded same-session continuation, and adds a loopback GoalBar for the exact bound loop.
Q00/ouroboros#integrations/dsh-plugin★ 6373
Config-only bundle that mounts Ouroboros through the DSH MCP client, exposing 36 interview, Seed, execution, evaluation, and evolution workflow tools in DSH.
chuspeeism/dashi-taskboard#deepseek-harness★ 3495
Embeds the active installed Codex Taskboard runtime in the DeepSeek Harness sidebar, using its launcher runtime descriptor instead of a fixed port.
NanmiCoder/dsh-agent-teams★ 2978
AgentTeams multi-agent teams.
EthanYoQ/AI-Novel-Writer#dsh-ai-novel-writer★ 2670
Installs a dedicated AI novel-writing preset and workbench: revisioned local project assets, a compact side drawer, and native approval-gated single-file changes.
shanliuling/dsh-image-gen★ 1576
Native conversational image generation for DeepSeek Harness: ask the agent to create an image, and it handles generation and keeps the result directly in the conversation.
Community comments
Comments are public GitHub Discussions. Loading them connects to GitHub and Giscus; a GitHub account is required to post.