@agent_forge/forge-dsh
Forge quality gates for DeepSeek Harness (dsh) — task gates, read-before-edit,
bash hazard interception, and quality scoring, enforced inside DSH sessions through
the harness's typed interception points.
Forge is an AI-code quality gate engine. This
plugin is a thin Cordis wrapper: it forwards DSH tool/session events to the forge
CLI and translates forge's verdicts back into DSH decisions. All gate logic lives in
the forge binary — the plugin itself has no third-party runtime dependencies
(无第三方运行时依赖); its only dependency is the pinned @agent_forge/forge package
that ships the binary (see Requirements below).
How it works
The mapping table below and the fail-open contract at the end of this README
are the two-sided bridge contract, mirrored machine-readably in
contract.json and enforced by forge's compat snapshot
(surface bridges). Change all three together: contract.json, this README,
and the tests on both sides.
| DSH interception point | forge hook event | A forge block becomes |
|---|
tools/pre-execute | PreToolUse | {kind:'deny', reason} |
tools/post-execute | PostToolUse | {kind:'block', feedback} (error result) |
agent/pre-step | UserPromptSubmit | {kind:'reject'} |
agent/session-start | SessionStart¹ | context queued, delivered with the next agent/pre-step² |
agent/turn-stopping | Stop | agent.steer(reason) → another step |
¹ source:'compact' additionally fires forge's PostCompact group — the preview
builds expose no dedicated compaction point.
² agent.inject() at session start was observed to drop the contexts silently, so they ride the
first pre-step instead; that pre-step waits up to startWaitMs (default 1500) for the detached
session-start run, and a rejected step keeps the queue for the next one.
DSH tool names map onto the Claude Code names forge dispatches on
(write/edit/str_replace_editor→Write/Edit, bash/pwsh→Bash, read/read_image→Read,
skill→Skill); unmapped tools pass ungated. The wired hook roster mirrors
forge's canonical spec (lib/spec.json, drift-guarded by a Go test in the Forge
repo) — freeze-guard, task-guard, assertion-check, read-before-edit, bash-guard,
hazard-guard, auto-compile, workflow-test-guard, file-sentinel, tool-track,
test-nudge, failure-track (PostToolUseFailure), subagent-track (SubagentStop),
task-verify, review-stop, skill-trigger, doc-lint, conventions-write, gate-cmd-form,
task-drift, resume-reinject, compact-resume, conventions-context, and the
session-start group.
failure-track/subagent-track are mirrored in the spec but inert until DSH
exposes the corresponding event points (the preview builds have neither).
Requirements
- The
forge CLI. The plugin depends on @agent_forge/forge (pinned to the plugin's
own version), so installing it through DSH installs forge and uninstalling removes
it — nothing to put on PATH. The bundled binary is not on PATH, so at session
start the agent is told its absolute path to run forge … commands with. Override
with forgeBin, or FORGE_BIN, to use a different forge. The project still needs
forge init for task gates to have state to enforce.
- DeepSeek Harness
0.1.0-rc.7 – 0.2.1-rc.2, Node.js ≥ 18. The bridge contract is
pinned to 0.1.0-rc.7 (contract.json); 0.2.1-rc.2 is the
desktop build this plugin runs on (pre-tool interception verified live there; a
full five-event regression across the range is still pending).
- Windows works out of the box: the bundled binary is
forge.exe, and a forge.cmd
shim from a global npm install is spawned through cmd.exe (a bare spawn cannot
execute it); timeout kills tear down the whole child tree via taskkill /T.
Install
<profile> is the dsh profile that is actually running. The desktop app runs the
desktop profile — installing into any other profile (e.g. web) succeeds but the
plugin never loads in the app. List your profiles under ~/.dsh/profiles/.
# from npm
dsh plugin --profile <profile> add @agent_forge/forge-dsh
# or straight from the Forge repo (subdirectory install)
dsh plugin --profile <profile> add "github:MjxUpUp/Forge#main&path:/plugins/forge-dsh"
# local development (run from this directory; `link:.` works on Windows too)
dsh plugin --profile <profile> add "link:."
The plugin hot-loads into a running dsh — adding or removing the bundle reloads the
profile. If a given build does not pick it up, restart the host once. Start a new
session to pick up the SessionStart context, and check the bridge's state with
/forge-status (probe result, wired groups, recent verdicts). To uninstall:
dsh plugin --profile <profile> remove @agent_forge/forge-dsh — the bundled forge goes
with it — or keep it installed but inert with enabled:false.
Config
Keys go on the bundle entry in the profile's cordis.patch.yml — the user-editable
patch layer. Do not edit the generated cordis.yml: the loader rewrites that root on
every boot, so anything written there is lost (the desktop app manages its own profile
under ~/.dsh/profiles/<profile>/):
# ~/.dsh/profiles/<profile>/cordis.patch.yml
- id: forge-quality
name: "@agent_forge/forge-dsh"
config:
forgeBin: forge # binary name/path. Precedence: this key > FORGE_BIN > bundled forge > PATH `forge`
timeoutMs: 30000 # per-hook ceiling; timeout kills and FAILS OPEN
startWaitMs: 1500 # first pre-step waits this long for session-start contexts
welcome: true # one first-turn line telling the user Forge is active (false = silent)
checkLatest: true # /forge-status compares the plugin version with the registry's latest (false = never ask)
locale: auto # language of the plugin's own messages: en | zh | auto (env FORGE_DSH_LOCALE, then system)
batch: auto # one forge process per matcher group: auto (default, needs a forge of the plugin's own version) | true | false
enabled: true # false unwires every listener
debug: false # log fail-open hook errors to console.error
Fail-open contract
Blocks are read from forge's stdout JSON (decision:"block"), never inferred from
exit codes: the verdict reason and its additionalContext exist only in that JSON,
and forge reuses exit 2 for hard errors as well. Every infrastructure failure (forge
missing, spawn error, unparseable output, timeout) fails open: a forge outage
never locks the agent out of its own tools. Such hook-run failures are silent by
design; surface them with /forge-status or debug:true.
A missing forge binary is the one exception to that silence: each session start
probes forge --version once (until a probe succeeds — the answer is then cached
for the process lifetime) and, when the probe fails, queues a visible notice
(delivered with the first pre-step) naming the configured forgeBin. Without it an uninstalled CLI would look exactly
like a healthy plugin gating nothing. The notice is informational, not a switch —
while the binary is missing, every hook attempt fails open on its own, so gates are
inactive whether or not the probe ran. Installing forge needs no host restart: the
next session probes again and gating resumes.
Two latency points to know. A matched group can run as one forge hook batch process
(forge runs the group's hooks in order and stops at the first block) instead of one process
per hook — roughly 2.4× faster on a measured PreToolUse/Bash group (716ms vs 1720ms on a loaded
dev machine). With the default batch: auto that happens only once the probe shows a forge of the
plugin's own version: batch asks forge to pick the group by the plugin's matcher string, and a forge
that disagrees would either print nothing on a block (older than the stdout fix) or silently run an
empty group, so any other forge stays on the per-hook path, which depends on hook names only. batch: true forces batch and gives that protection up (with a mismatched forge a group can run empty without
any error); use it only with a forge you know matches. false forces per-hook. Whatever the mode, a batch that fails is never taken as an
allow: that group is re-run per hook for the call (hooks the batch already ran may run again;
observation-only ones are de-duplicated by forge). Three failures in a row switch batch off; a batch
that times out keeps just that group per-hook for ten minutes, then tries it again, because batch gives
the whole group one timeoutMs and a single hung hook would otherwise starve the gates behind it. The
three-failures count is per group. /forge-status shows
all of this. And a gate that legitimately exceeds timeoutMs (e.g. auto-compile cold-building a large
project past 30s) silently loses that run's feedback to fail-open (visible in /forge-status). Raise
timeoutMs on big projects.
A session whose gates keep failing open used to look healthy while checking nothing. After
three fail-open runs in one session the plugin says so once, at the next Stop that is not
already steering for a real block: how many runs lost their feedback, where to look
(/forge-status) and what to raise (timeoutMs). It is advisory — nothing is blocked. The batch
to per-hook downgrade is not counted: that run still executed its gates.
The plugin delivers the bridge and (as a dependency) the forge CLI, not the skill library
DSH reads from ~/.agents/skills. When that directory holds no skill, the first-turn onboarding adds
one line offering forge skills install --global --target agents; the model runs it only after
the user agrees, since it writes the home directory. The offer is made once per host process, so
a user who declines is not asked again at every new session. Resume, subagents and
welcome: false sessions get no offer.
Whether forge takes over a project is asked once per project — the same on every host. Forge
does not infer consent from "the plugin is installed" (init-suggest's takeover preference is
the opt-in), so a DSH install behaves like a Claude Code plugin install here; the model relays
the question from forge's own init-suggest advisory, which the receipt filter below never drops.
Status-only receipts that forge prints when it has nothing to say (no weakening detected,
all skills SAFE, no .mcp.json …) are dropped before injection — the host turns every allow
context into a synthetic user message, and these carry no instruction. Anything else, including
notes the plugin has never seen, passes through.
/forge-status opens with plugin: <installed> latest: <registry> — an old install keeps working but
silently misses fixes, and this is the one place a user looks when something seems off. It is a single
read-only request with a 3-second timeout, made only when the command runs (never at load or session
start); offline, a private registry or an odd answer shows unknown, and checkLatest: false never asks.
It also reports a dispatch: line (batch or per-hook) and the probe line after the
header: probe: ok (forge version …), probe: FAILED — gates inactive (…), or not run yet before the process's first session start. It also lists wall time per interception
point (runs, average, max) and each recent run's duration.
Known watch items (dsh preview)
- No stop-hook loop guard in the preview builds (
0.1.0-rc.7 – 0.2.1-rc.2) —
a permanently-failing Stop gate steers at every stop boundary. forge's Stop gates
are self-limiting once their gate passes, but a stuck gate loops the turn.
- SessionStart context rides the first pre-step: the detached run is awaited for at
most
startWaitMs; a session whose first step arrives sooner than the run finishes
gets the context with its next step instead of the first.
- DSH is a developer preview; pin this plugin's version alongside your dsh version.
Development
npm install --no-package-lock # @deepseek-ai/cordis for the wiring tests (+ the bundled forge, unused by them)
npm test # mapping, runner (incl. cross-OS planSpawn units), decision folding, real-cordis wiring
test/doubles/fake-forge.mjs stands in for the forge binary; the wiring suite
boots a real cordis runtime and asserts dispatch order, short-circuit semantics,
payload shape, and every decision mapping.
