@agent_forge/forge-dsh 0.1.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 MjxUpUp
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,101 @@
+# @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](https://github.com/MjxUpUp/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 **zero runtime dependencies**.
+
+## How it works
+
+| 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 via `agent.inject()` |
+| `agent/turn-stopping` | `Stop` | `agent.steer(reason)` → another step |
+
+¹ `source:'compact'` additionally fires forge's `PostCompact` group — DSH rc.7
+exposes no dedicated compaction point.
+
+DSH tool names map onto the Claude Code names forge dispatches on
+(`write/edit/str_replace_editor→Write/Edit`, `bash/pwsh→Bash`, `read→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,
+task-verify, review-stop, skill-trigger, and the session-start group.
+
+## Requirements
+
+- The `forge` CLI on `PATH` (`npm install -g @agent_forge/forge`), with the project
+  initialized (`forge init`) for task gates to have state to enforce.
+- DeepSeek Harness `0.1.0-rc.x` (verified against `0.1.0-rc.7`), Node.js ≥ 18.
+
+## Install
+
+```sh
+# from npm
+dsh plugin --profile web add @agent_forge/forge-dsh
+
+# or straight from the Forge repo (subdirectory install)
+dsh plugin --profile web add "github:MjxUpUp/Forge#main&path:/plugins/forge-dsh"
+
+# local development
+dsh plugin --profile web add "link:$(pwd)"
+```
+
+Restart `dsh web` after install. Check status inside a session with `/forge-status`.
+
+## Config
+
+```yaml
+# profile patch
+- insert:
+    - id: forge-quality
+      name: "@agent_forge/forge-dsh"
+      config:
+        forgeBin: forge      # binary name/path (env FORGE_BIN overrides the default)
+        timeoutMs: 30000     # per-hook ceiling; timeout kills and FAILS OPEN
+        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 from exit
+codes — a forge internal error (exit 1) is indistinguishable from a deny otherwise.
+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 failures are silent by design; surface them with `/forge-status` or `debug:true`.
+
+Two latency trade-offs to know: hooks run **serially** per event (up to five per
+group), so a slow hook chain delays the tool call — 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.
+
+## Known watch items (dsh preview)
+
+- **No stop-hook loop guard** in rc.7 — 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 is best-effort** (emit mode, detached): it may miss the
+  first request of a very short-lived session — same limitation the official
+  bridges document (`TODO(session-start-gating)`).
+- DSH is a developer preview; pin this plugin's version alongside your dsh version.
+
+## Development
+
+```sh
+npm install   # dev-only: @deepseek-ai/cordis for the wiring tests
+npm test      # 33 tests: mapping, runner, 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.

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: forge-quality
+      name: "@agent_forge/forge-dsh"

package/lib/decisions.js

@@ -0,0 +1,185 @@
+/**
+ * @agent_forge/forge-dsh — decision folding (pure logic, no I/O).
+ *
+ * One forge hook group (a spec event's matched commands) runs serially and
+ * collapses to `{ blocked?, contexts, errors }`:
+ *   - the first block wins and short-circuits the rest of the group (the
+ *     spec's own ordering contract — freeze-guard runs first precisely so its
+ *     deny pre-empts task-guard's);
+ *   - allow-path additionalContext strings accumulate in order;
+ *   - infrastructure failures (fail-open verdicts) are collected for
+ *     observability but never influence the outcome.
+ *
+ * The collapse then maps onto DSH's typed decisions per interception point
+ * (see index.js): deny for tools/pre-execute, block+feedback for
+ * tools/post-execute, reject for agent/pre-step, steering for
+ * agent/turn-stopping.
+ *
+ * @module decisions
+ */
+
+import { runForgeHook } from "./runner.js";
+import { pluginMessage } from "./tools.js";
+
+/**
+ * @typedef {object} GroupOutcome
+ * @property {{reason: string, command: string}|undefined} blocked
+ * @property {string[]} contexts - allow-path additionalContext, in order.
+ * @property {string[]} errors   - fail-open infrastructure notes.
+ */
+
+/**
+ * Run one matched hook group serially against one payload.
+ *
+ * @param {string[]} commands - `forge hook <name>` commands, spec order.
+ * @param {object} payload    - Claude-Code-shape stdin payload (shared by the
+ *                              whole group, as in Claude Code).
+ * @param {object} [opts]     - forwarded to runForgeHook (forgeBin/timeoutMs/cwd).
+ * @returns {Promise<GroupOutcome>}
+ */
+export async function runHookGroup(commands, payload, opts = {}) {
+  const run = opts.runner ?? runForgeHook; // DI seam for tests
+  const outcome = { blocked: undefined, contexts: [], errors: [] };
+  for (const command of commands) {
+    const verdict = await run(command, payload, opts);
+    if (verdict.error !== undefined) outcome.errors.push(`${command}: ${verdict.error}`);
+    if (verdict.block) {
+      outcome.blocked = { reason: verdict.reason ?? "denied", command };
+      break;
+    }
+    if (verdict.context !== undefined) outcome.contexts.push(verdict.context);
+  }
+  return outcome;
+}
+
+/**
+ * tools/pre-execute: forge block → deny; otherwise delegate. Allow-path
+ * context has no channel on PreToolDecision (allow carries nothing), so it is
+ * queued into the agent's next pre-step via agent.inject — the seam dsh-agent
+ * documents for exactly this ("Queue model-facing context for the next
+ * pre-step without waking the driver").
+ *
+ * @param {GroupOutcome} outcome
+ * @param {object|undefined} agent
+ * @param {() => Promise<object>} next
+ * @returns {Promise<object>} PreToolDecision
+ */
+export async function preExecuteDecision(outcome, agent, next) {
+  if (outcome.blocked !== undefined) {
+    return { kind: "deny", reason: outcome.blocked.reason };
+  }
+  injectContexts(agent, outcome.contexts);
+  return next();
+}
+
+/**
+ * tools/post-execute: forge block → block with the reason as corrective
+ * feedback (the post-execute "block turns corrective feedback into an error
+ * result" channel). The block variant of PostToolDecision carries NO
+ * additionalContexts (that field belongs to accept), so contexts gathered
+ * before the block are queued via agent.inject instead of being attached to
+ * a decision shape the runtime would drop (or worse, reject on a stricter
+ * schema check). Allow-path context folds into the downstream decision AFTER
+ * delegating (delegate-then-prepend: returning an enter-style decision
+ * without next() would short-circuit every later listener).
+ *
+ * @param {GroupOutcome} outcome
+ * @param {() => Promise<object>} next
+ * @param {object|undefined} [agent] - for the block-path context fallback.
+ * @returns {Promise<object>} PostToolDecision
+ */
+export async function postExecuteDecision(outcome, next, agent) {
+  if (outcome.blocked !== undefined) {
+    injectContexts(agent, outcome.contexts);
+    return {
+      kind: "block",
+      feedback: [{ type: "text", text: outcome.blocked.reason }],
+    };
+  }
+  const decision = await next();
+  if (outcome.contexts.length === 0) return decision;
+  return {
+    ...decision,
+    additionalContexts: [
+      ...outcome.contexts.map(pluginMessage),
+      ...(decision?.additionalContexts ?? []),
+    ],
+  };
+}
+
+/**
+ * agent/pre-step (UserPromptSubmit): forge block → reject the step. PreStepDecision's
+ * reject variant carries no reason, so the gate's corrective feedback (and any
+ * same-group contexts) is queued via agent.inject first — on Claude Code the
+ * UserPromptSubmit block reason reaches the user, and it must not silently
+ * vanish here. Allow-path context prepends plugin messages into the
+ * downstream enter decision (reject passes through untouched).
+ *
+ * @param {GroupOutcome} outcome
+ * @param {() => Promise<object>} next
+ * @param {object|undefined} [agent] - for the reject-path reason/context fallback.
+ * @returns {Promise<object>} PreStepDecision
+ */
+export async function preStepDecision(outcome, next, agent) {
+  if (outcome.blocked !== undefined) {
+    injectContexts(agent, [outcome.blocked.reason, ...outcome.contexts]);
+    return { kind: "reject" };
+  }
+  const decision = await next();
+  if (outcome.contexts.length === 0 || decision?.kind !== "enter") return decision;
+  return {
+    kind: "enter",
+    messages: [...outcome.contexts.map(pluginMessage), ...decision.messages],
+  };
+}
+
+/**
+ * agent/turn-stopping (Stop): forge block steers the agent into another step
+ * (dsh-agent: "a listener that objects steers and the machine re-reads its
+ * inbox: fresh steering runs another step, none closes the turn"); allow-path
+ * context is queued via inject.
+ *
+ * NOTE: DSH rc.7 has no stop-hook loop guard (the official bridges always
+ * report stop_hook_active:false for the same reason). forge's Stop hooks are
+ * gate-driven and self-limiting (a passing gate stops blocking), but a
+ * permanently-failing gate will steer every stop boundary — surfaced in the
+ * README as a known watch item.
+ *
+ * @param {GroupOutcome} outcome
+ * @param {object} agent
+ * @returns {Promise<void>}
+ */
+export async function turnStoppingOutcome(outcome, agent) {
+  if (outcome.blocked !== undefined) {
+    agent?.steer?.(pluginMessage(outcome.blocked.reason));
+    return;
+  }
+  injectContexts(agent, outcome.contexts);
+}
+
+/**
+ * agent/session-start (emit): every collected context is queued via inject.
+ * Best-effort by design — emit listeners are detached, so context may miss
+ * the first request of a short-lived session (the official bridges document
+ * the same TODO(session-start-gating) limitation).
+ *
+ * @param {GroupOutcome} outcome
+ * @param {object} agent
+ */
+export function sessionStartOutcome(outcome, agent) {
+  injectContexts(agent, outcome.contexts);
+}
+
+/** Queue each context string as one plugin-sourced message. */
+function injectContexts(agent, contexts) {
+  if (contexts.length === 0) return;
+  const inject = agent?.inject;
+  if (typeof inject !== "function") return;
+  for (const text of contexts) {
+    try {
+      inject.call(agent, pluginMessage(text));
+    } catch {
+      // a throwing inject must never interrupt the session (bridge isolation rule)
+    }
+  }
+}

package/lib/index.js

@@ -0,0 +1,167 @@
+/**
+ * @agent_forge/forge-dsh — Forge quality gates for DeepSeek Harness.
+ *
+ * Wires forge's Claude-Code hook roster (mirrored in lib/spec.json from
+ * internal/hooks/settings.go ForgeHookSpec — drift-guarded by a Go test in
+ * the Forge repo) onto DSH's typed interception points:
+ *
+ *   tools/pre-execute   → PreToolUse  (block → {kind:'deny'})
+ *   tools/post-execute  → PostToolUse (block → {kind:'block', feedback})
+ *   agent/pre-step      → UserPromptSubmit (block → {kind:'reject'})
+ *   agent/session-start → SessionStart (emit; source 'compact' also fires
+ *                         the PostCompact group — DSH rc.7 exposes no
+ *                         separate compaction point)
+ *   agent/turn-stopping → Stop        (block → agent.steer(reason))
+ *
+ * Each hook runs as `forge hook <name>` with a Claude-Code-shape stdin
+ * payload and speaks forge's claude stdout dialect back (block read from the
+ * JSON decision field; every infrastructure failure fails open — a forge
+ * outage never locks the agent out of its tools). Verified against
+ * @deepseek-ai/dsh 0.1.0-rc.7 type surface.
+ *
+ * Config (profile patch):
+ *   forgeBin  - forge binary name/path (default "forge", env FORGE_BIN wins over default)
+ *   timeoutMs - per-hook ceiling, kill + fail open (default 30000)
+ *   enabled   - false disables every listener (default true)
+ *   debug     - log hook failures to console.error (default false)
+ *
+ * @module @agent_forge/forge-dsh
+ */
+import { readFileSync } from "node:fs";
+import { runHookGroup, preExecuteDecision, postExecuteDecision, preStepDecision, turnStoppingOutcome, sessionStartOutcome } from "./decisions.js";
+import { buildEventPayload, buildToolPayload, matchedCommands, promptText, toCCToolName } from "./tools.js";
+
+const spec = JSON.parse(readFileSync(new URL("./spec.json", import.meta.url), "utf8"));
+
+/** Stable Cordis plugin name. */
+const name = "forge-quality";
+/** Hard dependency: the tool registry (pre/post-execute waterfalls). */
+const inject = ["tools"];
+
+/**
+ * @param {object} ctx - Cordis plugin context.
+ * @param {object} [config] - { forgeBin?, timeoutMs?, enabled?, debug? }.
+ */
+function apply(ctx, config = {}) {
+  if (config.enabled === false) return;
+  const opts = {
+    forgeBin: config.forgeBin ?? process.env.FORGE_BIN ?? "forge",
+    timeoutMs: config.timeoutMs ?? 30000,
+  };
+  const debug = config.debug === true;
+  // Recent-run ring buffer for /forge-status — fail-open verdicts are silent
+  // by design, so this (plus debug logging) is the only way to see them.
+  const recentRuns = [];
+  const noteErrors = (label, outcome) => {
+    recentRuns.push({
+      label,
+      blocked: outcome.blocked?.command ?? null,
+      contexts: outcome.contexts.length,
+      errors: outcome.errors,
+      at: Date.now(),
+    });
+    if (recentRuns.length > 50) recentRuns.shift();
+    if (debug && outcome.errors.length > 0) {
+      console.error(`[forge-dsh] ${label} fail-open: ${outcome.errors.join("; ")}`);
+    }
+  };
+
+  // PreToolUse — deny short-circuits the tool call.
+  ctx.effect(() => ctx.on("tools/pre-execute", async (exec, next) => {
+    const commands = matchedCommands(spec.PreToolUse, toCCToolName(exec?.name ?? ""));
+    if (commands.length === 0) return next();
+    const outcome = await runHookGroup(commands, buildToolPayload(exec, "PreToolUse"), opts);
+    noteErrors("pre-execute", outcome);
+    return preExecuteDecision(outcome, exec?.agent, next);
+  }), "forge: pre-execute");
+
+  // PostToolUse — block turns the gate's reason into an error result.
+  ctx.effect(() => ctx.on("tools/post-execute", async (exec, result, next) => {
+    const commands = matchedCommands(spec.PostToolUse, toCCToolName(exec?.name ?? ""));
+    if (commands.length === 0) return next();
+    const outcome = await runHookGroup(commands, buildToolPayload(exec, "PostToolUse"), opts);
+    noteErrors("post-execute", outcome);
+    return postExecuteDecision(outcome, next, exec?.agent);
+  }), "forge: post-execute");
+
+  // UserPromptSubmit — the prompt rides the step's claimed messages.
+  ctx.effect(() => ctx.on("agent/pre-step", async (payload, next) => {
+    const commands = matchedCommands(spec.UserPromptSubmit, "");
+    if (commands.length === 0) return next();
+    const eventPayload = buildEventPayload("UserPromptSubmit", payload?.agent, {
+      prompt: promptText(payload?.messages),
+    });
+    const outcome = await runHookGroup(commands, eventPayload, opts);
+    noteErrors("pre-step", outcome);
+    return preStepDecision(outcome, next, payload?.agent);
+  }), "forge: pre-step");
+
+  // SessionStart — emit mode: detached, contexts queued via agent.inject.
+  // source 'compact' doubles as PostCompact (DSH exposes no dedicated point).
+  ctx.effect(() => ctx.on("agent/session-start", (payload) => {
+    const agent = payload?.agent;
+    const source = payload?.source;
+    (async () => {
+      const start = await runHookGroup(
+        matchedCommands(spec.SessionStart, ""),
+        buildEventPayload("SessionStart", agent, { source }),
+        opts,
+      );
+      noteErrors("session-start", start);
+      sessionStartOutcome(start, agent);
+      if (source === "compact") {
+        const compact = await runHookGroup(
+          matchedCommands(spec.PostCompact, ""),
+          buildEventPayload("PostCompact", agent, {}),
+          opts,
+        );
+        noteErrors("post-compact", compact);
+        sessionStartOutcome(compact, agent);
+      }
+    })().catch((error) => {
+      if (debug) console.error(`[forge-dsh] session-start failed open: ${error}`);
+    });
+  }), "forge: session-start");
+
+  // Stop — a blocking gate steers the agent into another step.
+  ctx.effect(() => ctx.on("agent/turn-stopping", async (payload) => {
+    const agent = payload?.agent;
+    const outcome = await runHookGroup(
+      matchedCommands(spec.Stop, ""),
+      buildEventPayload("Stop", agent, { stop_hook_active: false }),
+      opts,
+    );
+    noteErrors("turn-stopping", outcome);
+    return turnStoppingOutcome(outcome, agent);
+  }), "forge: turn-stopping");
+
+  // /forge-status — wired groups + recent runs (the only place fail-open
+  // infrastructure errors surface without debug:true).
+  const commands = ctx.get("commands");
+  if (commands !== undefined) {
+    ctx.effect(() => commands.register({
+      name: "forge-status",
+      description: "Forge quality gates: wired hook groups and recent runs",
+      handler: async () => {
+        const groups = Object.entries(spec)
+          .map(([event, gs]) => `  ${event}: ${gs.flatMap((g) => g.hooks.map((h) => h.command.replace("forge hook ", ""))).join(", ")}`)
+          .join("\n");
+        const runs = recentRuns.length === 0
+          ? "  (no hook runs yet)"
+          : recentRuns.slice(-10).map((r) => {
+              const parts = [`  ${new Date(r.at).toISOString()} ${r.label}`];
+              if (r.blocked) parts.push(`blocked-by=${r.blocked}`);
+              if (r.contexts > 0) parts.push(`contexts=${r.contexts}`);
+              if (r.errors.length > 0) parts.push(`FAIL-OPEN: ${r.errors.join("; ")}`);
+              return parts.join("  ");
+            }).join("\n");
+        return {
+          kind: "success",
+          text: `# Forge quality gates\n\nforgeBin: ${opts.forgeBin}  timeoutMs: ${opts.timeoutMs}\n\n## Wired groups\n${groups}\n\n## Recent runs (last 10)\n${runs}`,
+        };
+      },
+    }), "forge: status command");
+  }
+}
+
+export { apply, inject, name };

package/lib/runner.js

@@ -0,0 +1,121 @@
+/**
+ * @agent_forge/forge-dsh — spawn layer.
+ *
+ * Runs one `forge hook <name>` command with a Claude-Code-shape JSON payload on
+ * stdin and parses forge's verdict from its stdout JSON. The contract is the
+ * one forge's claude emitter writes (internal/cli/hook.go emitClaudeOutput):
+ *
+ *   pass, no detail : exit 0, empty stdout
+ *   pass + detail   : exit 0, {"hookSpecificOutput":{"hookEventName","additionalContext"}}
+ *   block           : exit 2, {"decision":"block","reason":...,"hookSpecificOutput":{...}}
+ *                     plus the reason on stderr
+ *
+ * Block is read from the JSON `decision` field — never from the exit code —
+ * because cobra reports forge's internal errors as exit 1, indistinguishable
+ * from a deny. Every infrastructure failure (forge missing, spawn error, JSON
+ * parse failure, timeout) FAILS OPEN so a forge outage never locks the agent
+ * out of its own tools. Same contract as the opencode/pi translators
+ * (internal/agentbridge/forge_spawn.ts).
+ *
+ * @module runner
+ */
+import { spawn } from "node:child_process";
+
+/**
+ * @typedef {object} HookVerdict
+ * @property {boolean} block    - forge denied the action.
+ * @property {string} [reason]  - block reason (shown to the model).
+ * @property {string} [context] - allow-path additionalContext to inject.
+ * @property {string} [error]   - infrastructure failure note (fail-open path).
+ */
+
+/**
+ * Run one forge hook command.
+ *
+ * @param {string} command - spec command, e.g. "forge hook task-guard".
+ * @param {object} payload - Claude-Code-shape hook stdin payload.
+ * @param {object} [opts]
+ * @param {string} [opts.forgeBin="forge"] - forge binary (path or PATH name).
+ * @param {number} [opts.timeoutMs=30000]  - kill + fail open past this.
+ * @param {string} [opts.cwd]              - working directory for the hook.
+ * @returns {Promise<HookVerdict>}
+ */
+export function runForgeHook(command, payload, opts = {}) {
+  const forgeBin = opts.forgeBin ?? "forge";
+  const timeoutMs = opts.timeoutMs ?? 30000;
+  const parts = command.split(" "); // ["forge","hook","task-guard"]
+  const argv = [forgeBin, ...parts.slice(1)];
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(argv[0], argv.slice(1), {
+        stdio: ["pipe", "pipe", "pipe"],
+        cwd: opts.cwd,
+      });
+    } catch (error) {
+      resolve({ block: false, error: note(error) });
+      return;
+    }
+    let out = "";
+    let settled = false;
+    // 30s default ceiling: a hung forge process (index.lock, blocked stdin,
+    // AV scan) would otherwise never resolve this Promise and freeze the
+    // agent's tool call forever. Timeout → kill + fail open.
+    const timer = setTimeout(() => {
+      if (settled) return;
+      settled = true;
+      try {
+        child.kill();
+      } catch {
+        // already exited — nothing to kill
+      }
+      resolve({ block: false, error: `timeout after ${timeoutMs}ms` });
+    }, timeoutMs);
+    const settle = (verdict) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(verdict);
+    };
+    child.stdout.on("data", (d) => (out += d.toString()));
+    child.on("error", (error) => settle({ block: false, error: note(error) }));
+    child.on("close", () => {
+      const text = out.trim();
+      if (text === "") return settle({ block: false });
+      try {
+        const j = JSON.parse(text);
+        const context = j?.hookSpecificOutput?.additionalContext;
+        if (j?.decision === "block") {
+          return settle({
+            block: true,
+            reason: j?.reason ?? context ?? "denied",
+          });
+        }
+        return settle({
+          block: false,
+          context: typeof context === "string" && context !== "" ? context : undefined,
+        });
+      } catch {
+        settle({ block: false, error: "unparseable forge stdout" });
+      }
+    });
+    // stdin error guard: a forge that exits WITHOUT reading stdin (unknown
+    // hook name after a version drift, a broken FORGE_BIN shim, an early
+    // panic) makes this write raise EPIPE on the stdin stream — an unhandled
+    // 'error' event here would crash the DSH HOST PROCESS, the exact opposite
+    // of the fail-open contract. The verdict itself still comes from
+    // close/stdout above; swallowing the stream error is sufficient.
+    //
+    // stdin 错误护栏：forge 不读 stdin 就提前退出（版本漂移后的未知 hook 名、
+    // 坏掉的 FORGE_BIN shim、早期 panic）会让这次写入在 stdin 流上抛
+    // EPIPE——此处未处理的 'error' 事件会**崩溃 DSH 宿主进程**，与
+    // fail-open 契约正好相反。判定仍由上面的 close/stdout 路径产出，吞掉
+    // 流错误即可。
+    child.stdin.on("error", () => {});
+    child.stdin.end(JSON.stringify(payload) + "\n");
+  });
+}
+
+function note(error) {
+  return (error instanceof Error ? error.message : String(error)).slice(0, 300);
+}

package/lib/spec.json

@@ -0,0 +1,80 @@
+{
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        { "type": "command", "command": "forge hook auto-compile" },
+        { "type": "command", "command": "forge hook workflow-test-guard" },
+        { "type": "command", "command": "forge hook skill-trigger" }
+      ]
+    },
+    {
+      "matcher": "Bash",
+      "hooks": [
+        { "type": "command", "command": "forge hook file-sentinel" },
+        { "type": "command", "command": "forge hook skill-trigger" }
+      ]
+    },
+    {
+      "matcher": "Read|Skill|Agent",
+      "hooks": [
+        { "type": "command", "command": "forge hook tool-track" }
+      ]
+    }
+  ],
+  "PreToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        { "type": "command", "command": "forge hook freeze-guard" },
+        { "type": "command", "command": "forge hook task-guard" },
+        { "type": "command", "command": "forge hook assertion-check" },
+        { "type": "command", "command": "forge hook read-before-edit" },
+        { "type": "command", "command": "forge hook skill-trigger" }
+      ]
+    },
+    {
+      "matcher": "Bash",
+      "hooks": [
+        { "type": "command", "command": "forge hook bash-guard" },
+        { "type": "command", "command": "forge hook hazard-guard" },
+        { "type": "command", "command": "forge hook skill-trigger" }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "hooks": [
+        { "type": "command", "command": "forge hook task-verify" },
+        { "type": "command", "command": "forge hook review-stop" },
+        { "type": "command", "command": "forge hook skill-trigger" }
+      ]
+    }
+  ],
+  "SessionStart": [
+    {
+      "hooks": [
+        { "type": "command", "command": "forge hook skill-scan" },
+        { "type": "command", "command": "forge hook mcp-scan" },
+        { "type": "command", "command": "forge hook init-suggest" },
+        { "type": "command", "command": "forge hook task-resume" },
+        { "type": "command", "command": "forge hook skill-trigger" }
+      ]
+    }
+  ],
+  "PostCompact": [
+    {
+      "hooks": [
+        { "type": "command", "command": "forge hook compact-resume" }
+      ]
+    }
+  ],
+  "UserPromptSubmit": [
+    {
+      "hooks": [
+        { "type": "command", "command": "forge hook resume-reinject" },
+        { "type": "command", "command": "forge hook skill-trigger" }
+      ]
+    }
+  ]
+}

package/lib/tools.js

@@ -0,0 +1,187 @@
+/**
+ * @agent_forge/forge-dsh — DSH → Claude-Code vocabulary mapping.
+ *
+ * forge's hook dispatch keys on Claude Code tool names (Write/Edit/Bash/Read/
+ * Skill/Agent) and Claude-shape payloads (HookInput in internal/cli/hook.go).
+ * DSH's built-in fs tools already use Claude-style argument field names
+ * (file_path/content/old_string/new_string — verified against
+ * @deepseek-ai/dsh-tool-fs 0.1.0-rc.7), so tool_input is a light alias pass
+ * rather than a deep translation.
+ *
+ * @module tools
+ */
+
+/** DSH built-in tool name → Claude Code tool name forge dispatches on. */
+export const CC_TOOL_NAME = {
+  write: "Write",
+  edit: "Edit",
+  str_replace_editor: "Edit", // Minimal preset's editor tool
+  bash: "Bash",
+  pwsh: "Bash",
+  read: "Read",
+  read_image: "Read",
+  skill: "Skill",
+};
+
+/**
+ * Map a DSH tool name to its Claude Code equivalent. Unknown names pass
+ * through unchanged — no spec matcher will match them, so they sail through
+ * the waterfalls ungated (same as an unmatched tool in Claude Code).
+ *
+ * @param {string} dshName
+ * @returns {string}
+ */
+export function toCCToolName(dshName) {
+  return CC_TOOL_NAME[dshName] ?? dshName;
+}
+
+/** Field aliases from non-CC argument shapes to Claude's tool_input keys. */
+const INPUT_ALIASES = {
+  filePath: "file_path",
+  path: "file_path",
+  newText: "content",
+};
+
+/**
+ * Normalize one tool's argument object into Claude tool_input shape. DSH fs
+ * tools already use file_path/content/old_string/new_string, so this mostly
+ * copies; aliases cover camelCase variants seen in community tools. The
+ * original arguments object is never mutated.
+ *
+ * @param {unknown} args
+ * @returns {Record<string, unknown>}
+ */
+export function normalizeToolInput(args) {
+  const out = {};
+  if (args === null || typeof args !== "object" || Array.isArray(args)) return out;
+  for (const [key, value] of Object.entries(args)) {
+    out[INPUT_ALIASES[key] ?? key] = value;
+  }
+  // A bare alias must not shadow an already-correct CC field (args carrying
+  // both file_path and path: file_path wins regardless of iteration order).
+  for (const [alias, canonical] of Object.entries(INPUT_ALIASES)) {
+    if (args[alias] !== undefined && args[canonical] !== undefined) {
+      out[canonical] = args[canonical];
+    }
+  }
+  return out;
+}
+
+/**
+ * Collect the spec hook commands of one event whose matcher accepts ccName.
+ * A group with an empty/absent matcher always matches; otherwise the matcher
+ * is an alternation regex tested against the Claude tool name (identical to
+ * Claude Code's matcher semantics for forge's own spec — every matcher in
+ * spec.json is a plain alternation like "Write|Edit").
+ *
+ * @param {Array<{matcher?: string, hooks: Array<{command: string}>}>} groups
+ * @param {string} ccName
+ * @returns {string[]} matched commands, in spec order
+ */
+export function matchedCommands(groups, ccName) {
+  const commands = [];
+  for (const group of groups ?? []) {
+    if (group.matcher !== undefined && group.matcher !== "") {
+      if (!new RegExp(`^(?:${group.matcher})$`).test(ccName)) continue;
+    }
+    for (const hook of group.hooks ?? []) commands.push(hook.command);
+  }
+  return commands;
+}
+
+/**
+ * Extract the session identity forge expects from a DSH agent handle.
+ * Falls back to process cwd and an empty session id (forge degrades to its
+ * legacy global state file for an empty session id — same degradation the
+ * official bridges accept when no transcript locator exists).
+ *
+ * @param {object|undefined} agent
+ * @returns {{ sessionId: string, cwd: string }}
+ */
+export function sessionBits(agent) {
+  const session = agent?.session;
+  return {
+    sessionId: session?.id ?? "",
+    cwd: session?.header?.cwd ?? process.cwd(),
+  };
+}
+
+/**
+ * Build the Claude-Code-shape stdin payload for one tool event.
+ *
+ * @param {object} exec - DSH ToolExecution ({name, arguments, agent?}).
+ * @param {"PreToolUse"|"PostToolUse"} event
+ * @returns {object}
+ */
+export function buildToolPayload(exec, event) {
+  const { sessionId, cwd } = sessionBits(exec?.agent);
+  return {
+    session_id: sessionId,
+    transcript_path: "",
+    cwd,
+    hook_event_name: event,
+    tool_name: toCCToolName(exec?.name ?? ""),
+    tool_input: normalizeToolInput(exec?.arguments),
+    forge_agent: "dsh",
+  };
+}
+
+/**
+ * Build the stdin payload for a non-tool event (Stop / SessionStart /
+ * UserPromptSubmit / PostCompact).
+ *
+ * @param {string} event
+ * @param {object|undefined} agent
+ * @param {object} [extra] - extra fields (prompt, source, stop_hook_active…).
+ * @returns {object}
+ */
+export function buildEventPayload(event, agent, extra = {}) {
+  const { sessionId, cwd } = sessionBits(agent);
+  return {
+    session_id: sessionId,
+    transcript_path: "",
+    cwd,
+    hook_event_name: event,
+    forge_agent: "dsh",
+    ...extra,
+  };
+}
+
+/**
+ * Concatenate the visible text of user messages into one prompt string
+ * (forge's UserPromptSubmit consumers read a flat `prompt` field).
+ *
+ * @param {Array<{content?: Array<{type: string, text?: string}>}>} messages
+ * @returns {string}
+ */
+export function promptText(messages) {
+  const parts = [];
+  for (const message of messages ?? []) {
+    for (const block of message?.content ?? []) {
+      if (block?.type === "text" && typeof block.text === "string") parts.push(block.text);
+    }
+  }
+  return parts.join("\n");
+}
+
+let messageSeq = 0;
+
+/**
+ * Build one plugin-sourced user message (the shape dsh-llm's
+ * createUserMessage freezes: role 'user', text content, plugin source).
+ * Constructed literally to keep this package dependency-free — importing
+ * @deepseek-ai/dsh-llm would only resolve when the install layout happens to
+ * nest it above us.
+ *
+ * @param {string} text
+ * @returns {{id: string, role: "user", content: Array<{type: "text", text: string}>, source: {kind: "plugin", plugin: string}}}
+ */
+export function pluginMessage(text) {
+  messageSeq += 1;
+  return {
+    id: `forge-dsh-${Date.now()}-${messageSeq}`,
+    role: "user",
+    content: [{ type: "text", text }],
+    source: { kind: "plugin", plugin: "forge-quality" },
+  };
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@agent_forge/forge-dsh",
+  "version": "0.1.0",
+  "description": "Forge quality gates for DeepSeek Harness (dsh): task gates, read-before-edit, bash hazard interception and quality scoring, driven by the forge CLI through DSH's typed interception points.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MjxUpUp/Forge",
+    "directory": "plugins/forge-dsh"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib/index.js",
+    "lib/runner.js",
+    "lib/decisions.js",
+    "lib/tools.js",
+    "lib/spec.json",
+    "cordis.patch.yml"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "scripts": {
+    "test": "node --test lib/*.test.js"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "quality-gates",
+    "hooks",
+    "ai-code-quality"
+  ],
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}