@agent_forge/forge-dsh 1.80.1 → 1.82.0

package/README.md

@@ -22,12 +22,16 @@ the forge binary — the plugin itself has **zero runtime dependencies**.
 | `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/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
@@ -43,35 +47,43 @@ exposes the corresponding event points (the preview builds have neither).
 
 ## 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.
+- 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`](./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: npm lays out `forge` as a `forge.cmd` shim, which
-  the plugin spawns through `cmd.exe` (a bare spawn cannot execute it); timeout
-  kills tear down the whole child tree via `taskkill /T`.
+- 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/`.
+
 ```sh
 # from npm
-dsh plugin --profile web add @agent_forge/forge-dsh
+dsh plugin --profile <profile> 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"
+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 web add "link:."
+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 <name> remove @agent_forge/forge-dsh` (the desktop app's profile
-is `desktop`), or keep it installed but inert with `enabled:false`.
+`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
 
@@ -84,8 +96,10 @@ under `~/.dsh/profiles/<profile>/`):
 - id: forge-quality
   name: "@agent_forge/forge-dsh"
   config:
-    forgeBin: forge      # binary name/path; FORGE_BIN only fills in when this key is absent
+    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)
     enabled: true        # false unwires every listener
     debug: false         # log fail-open hook errors to console.error
 ```
@@ -101,8 +115,8 @@ 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, injects a visible notice
-naming the configured `forgeBin`. Without it an uninstalled CLI would look exactly
+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
@@ -131,7 +145,7 @@ session start.
 ## Development
 
 ```sh
-npm install   # dev-only: @deepseek-ai/cordis for the wiring tests
+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
 ```
 

package/lib/bundled.js

@@ -0,0 +1,87 @@
+/**
+ * @agent_forge/forge-dsh — bundled forge binary resolution.
+ *
+ * The plugin depends on `@agent_forge/forge` (version-locked to the plugin by the
+ * release train), so installing the plugin through DSH's pnpm also installs the
+ * forge CLI, and uninstalling removes it. That package ships no install script —
+ * its binary arrives as a per-platform optionalDependency
+ * (`@agent_forge/forge-<os>-<arch>`, os/cpu-filtered by the package manager) — so
+ * resolving it here needs no PATH entry and skips the `forge` node shim
+ * (~200ms per spawn).
+ *
+ * 插件依赖 `@agent_forge/forge`（与插件同版本发版），经 DSH 的 pnpm 安装插件时
+ * 本体随之安装、卸载插件时随之移除。本体二进制来自平台子包，这里直接解析其
+ * 绝对路径：不依赖 PATH，也省掉 node shim 的每次约 200ms。
+ *
+ * @module bundled
+ */
+import { createRequire } from "node:module";
+
+/** Platforms the forge npm package ships a binary for (npm/run.js SUPPORTED). */
+const SUPPORTED = new Set(["darwin-arm64", "darwin-x64", "linux-arm64", "linux-x64", "win32-x64"]);
+
+/**
+ * Platform subpackage name and executable file name for one os/arch, or
+ * undefined when forge ships no binary for it.
+ *
+ * @param {string} [platform] - process.platform override (tests).
+ * @param {string} [arch] - process.arch override (tests).
+ * @returns {{name: string, exe: string}|undefined}
+ */
+export function platformPackage(platform = process.platform, arch = process.arch) {
+  const key = `${platform}-${arch}`;
+  if (!SUPPORTED.has(key)) return undefined;
+  return { name: `@agent_forge/forge-${key}`, exe: platform === "win32" ? "forge.exe" : "forge" };
+}
+
+/**
+ * Absolute path of the bundled forge binary, or undefined when it is not
+ * installed (dependency omitted, optional subpackage skipped, unsupported
+ * platform). Never throws — an unresolvable bundle simply falls back to the
+ * PATH `forge`, and the missing-CLI probe covers the rest.
+ *
+ * Resolution tries the platform package as seen from `@agent_forge/forge`
+ * first (correct under pnpm's isolated linker, where the subpackage is only
+ * reachable from the main package), then directly from the plugin (hoisted
+ * layout, which is what DSH profiles use).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.platform]
+ * @param {string} [opts.arch]
+ * @param {string|URL} [opts.from] - module URL resolution starts from (tests).
+ * @returns {string|undefined}
+ */
+export function resolveBundledForge(opts = {}) {
+  const pkg = platformPackage(opts.platform, opts.arch);
+  if (pkg === undefined) return undefined;
+  const target = `${pkg.name}/bin/${pkg.exe}`;
+  const pluginRequire = createRequire(opts.from ?? import.meta.url);
+  try {
+    const mainPackageJson = pluginRequire.resolve("@agent_forge/forge/package.json");
+    return createRequire(mainPackageJson).resolve(target);
+  } catch {
+    // main package absent or its subpackage not reachable from it — try the plugin's own view
+  }
+  try {
+    return pluginRequire.resolve(target);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * One line telling the agent where forge lives. The bundled binary is not on
+ * PATH, while forge's own gate messages say `forge task start …`; gates are
+ * driven by the agent, so it needs the absolute path to run them.
+ *
+ * @param {string} binPath - absolute path from resolveBundledForge.
+ * @returns {string}
+ */
+export function bundledForgeHint(binPath) {
+  const shown = /\s/.test(binPath) ? `"${binPath}"` : binPath;
+  return (
+    `[forge-dsh] forge CLI bundled with this plugin: ${shown}. It may not be on PATH — ` +
+    "when a gate message or the protocol tells you to run a `forge …` command, " +
+    `run it with this path instead of \`forge\`.`
+  );
+}

package/lib/decisions.js

@@ -158,16 +158,30 @@ export async function turnStoppingOutcome(outcome, agent) {
 }
 
 /**
- * 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).
+ * agent/session-start (emit) contexts ride the NEXT pre-step instead of
+ * agent.inject. Emit listeners are detached and inject at session start was
+ * observed to drop the contexts silently (audit 2026-10-20: all four lost,
+ * not delayed, while pre-step messages in the same session were delivered), so
+ * the queued strings are prepended into the first `enter` decision. A reject
+ * (or any non-enter decision) leaves the queue to the caller — it must retain
+ * the strings for the next pre-step.
  *
- * @param {GroupOutcome} outcome
- * @param {object} agent
+ * 会话启动的上下文改走下一次 pre-step 的 enter 决策（而非 agent.inject）：
+ * 实测 inject 在会话启动时静默丢弃，pre-step 消息则稳定送达。
+ *
+ * @param {object} decision - PreStepDecision (after preStepDecision folding).
+ * @param {string[]} pending - queued session-start contexts, delivery order.
+ * @returns {{decision: object, delivered: boolean}} delivered=true means the
+ *   caller may clear the queue.
  */
-export function sessionStartOutcome(outcome, agent) {
-  injectContexts(agent, outcome.contexts);
+export function prependStartContexts(decision, pending) {
+  if (pending.length === 0 || decision?.kind !== "enter") {
+    return { decision, delivered: false };
+  }
+  return {
+    decision: { ...decision, messages: [...pending.map(pluginMessage), ...(decision.messages ?? [])] },
+    delivered: true,
+  };
 }
 
 /** Queue each context string as one producer-attributed user message. */

package/lib/index.js

@@ -10,7 +10,8 @@
  *   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)
+ *                         separate compaction point). Its contexts are queued
+ *                         per agent and delivered with the next pre-step.
  *   agent/turn-stopping → Stop        (block → agent.steer(reason))
  *
  * Each hook runs as `forge hook <name>` with a Claude-Code-shape stdin
@@ -20,19 +21,26 @@
  * @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)
+ *   forgeBin  - forge binary name/path. Precedence: config > env FORGE_BIN >
+ *               the forge bundled with this plugin (dependency, version-locked) >
+ *               "forge" on PATH
  *   timeoutMs - per-hook ceiling, kill + fail open (default 30000)
+ *   welcome   - false drops the one-line first-turn onboarding (default true)
+ *   startWaitMs - how long the first pre-step waits for the session-start
+ *               contexts before moving on without them (default 1500)
  *   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 { bundledForgeHint, resolveBundledForge } from "./bundled.js";
 import { probeForge } from "./runner.js";
-import { runHookGroup, preExecuteDecision, postExecuteDecision, preStepDecision, turnStoppingOutcome, sessionStartOutcome } from "./decisions.js";
-import { buildEventPayload, buildToolPayload, matchedCommands, pluginMessage, promptText, toCCToolName } from "./tools.js";
+import { runHookGroup, preExecuteDecision, postExecuteDecision, preStepDecision, prependStartContexts, turnStoppingOutcome } from "./decisions.js";
+import { buildEventPayload, buildToolPayload, matchedCommands, promptText, toCCToolName, welcomeText, isSubagent, MANAGED_BANNER } from "./tools.js";
 
 const spec = JSON.parse(readFileSync(new URL("./spec.json", import.meta.url), "utf8"));
+const pluginVersion = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
 /** Stable Cordis plugin name. */
 const name = "forge-quality";
@@ -45,11 +53,23 @@ const inject = ["tools"];
  */
 function apply(ctx, config = {}) {
   if (config.enabled === false) return;
+  const explicitBin = config.forgeBin ?? process.env.FORGE_BIN;
+  let bundledBin;
+  if (explicitBin === undefined) {
+    try {
+      bundledBin = (config.resolveBundledForge ?? resolveBundledForge)(); // config seam: tests
+    } catch {
+      bundledBin = undefined; // an unresolvable bundle must never break plugin load
+    }
+  }
+  let binSource = explicitBin !== undefined ? "configured" : bundledBin !== undefined ? "bundled" : "PATH";
   const opts = {
-    forgeBin: config.forgeBin ?? process.env.FORGE_BIN ?? "forge",
+    forgeBin: explicitBin ?? bundledBin ?? "forge",
     timeoutMs: config.timeoutMs ?? 30000,
   };
   const debug = config.debug === true;
+  const welcome = config.welcome !== false;
+  const startWaitMs = Number.isFinite(config.startWaitMs) && config.startWaitMs >= 0 ? config.startWaitMs : 1500;
   // 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 = [];
@@ -67,21 +87,60 @@ function apply(ctx, config = {}) {
     }
   };
 
+  // Session-start contexts (forge's own onboarding + the missing-forge notice)
+  // are queued per agent and prepended into that agent's next pre-step.
+  // agent.inject at session start was observed to drop them silently, while
+  // pre-step messages in the same session were delivered. The session-start
+  // run is detached and takes a few hundred ms, so the first pre-step may
+  // arrive before it finishes: `ready` lets that pre-step wait a bounded time
+  // (startWaitMs) instead of pushing the onboarding to turn 2.
+  // Keyed by session id when the handle has one (the host may hand each event a
+  // fresh wrapper object for the same session), by object identity otherwise.
+  const startStates = new WeakMap();
+  const startStatesById = new Map();
+  const startStateOf = (agent) => {
+    if (agent === null || typeof agent !== "object") return undefined;
+    const id = agent.session?.id;
+    const byId = typeof id === "string" && id !== "";
+    let state = byId ? startStatesById.get(id) : startStates.get(agent);
+    if (state === undefined) {
+      state = { pending: [], ready: Promise.resolve(), waited: true };
+      if (byId) startStatesById.set(id, state);
+      else startStates.set(agent, state);
+    }
+    return state;
+  };
+  // Only the first pre-step after a session-start waits: a slow start run must
+  // not tax every later step by startWaitMs; its contexts simply land on the
+  // first enter after it finishes.
+  const waitStart = async (state) => {
+    if (state === undefined || state.waited) return;
+    state.waited = true;
+    let timer;
+    const timeout = new Promise((resolve) => {
+      timer = setTimeout(resolve, startWaitMs);
+      timer.unref?.();
+    });
+    try {
+      await Promise.race([state.ready, timeout]);
+    } finally {
+      clearTimeout(timer);
+    }
+  };
+
   // A missing forge binary used to be completely silent: every hook failed
   // open, so the plugin looked installed but gated nothing. Probe once per
   // session start (retrying on later sessions, since installing forge needs no
-  // host restart) and surface the failure through agent.inject — the same
-  // channel forge's own advisories use. Once a probe succeeds the answer is
-  // cached for the process lifetime; forgeBin is static config per plugin
-  // instance, so it cannot go stale.
+  // host restart) and surface the failure through the same start queue. Once a
+  // probe succeeds the answer is cached for the process lifetime; forgeBin is
+  // static config per plugin instance, so it cannot go stale.
   let forgeReady = false;
   let lastProbe;
   let probeInFlight;
-  const noticedAgents = new WeakSet();
   const missingForgeNotice = (error) =>
     `[forge-dsh] forge CLI not found (forgeBin: ${opts.forgeBin}). ` +
     "Forge gates are OFF for this session — every action runs unguarded (fail-open). " +
-    "Install it with `npm install -g @agent_forge/forge`, then start a new session; " +
+    "Reinstall the plugin (it bundles forge) or run `npm install -g @agent_forge/forge`, then start a new session; " +
     "if it lives elsewhere, set forgeBin in the profile patch." +
     (error === undefined ? "" : `\nProbe error: ${error}`);
   const ensureForge = async (agent) => {
@@ -92,20 +151,28 @@ function apply(ctx, config = {}) {
           probeInFlight = undefined;
         });
     }
-    const probe = await probeInFlight;
+    let probe = await probeInFlight;
+    // A bundled binary that resolved but will not run (wrong arch, lost exec bit,
+    // truncated download) must not void the gates when a working forge is on PATH.
+    if (!probe.ok && binSource === "bundled") {
+      const onPath = await probeForge({ forgeBin: "forge", timeoutMs: Math.min(opts.timeoutMs, 5000) });
+      if (onPath.ok) {
+        if (debug) console.error(`[forge-dsh] bundled forge unusable (${probe.error}); using PATH forge`);
+        opts.forgeBin = "forge";
+        binSource = "PATH";
+        probe = onPath;
+      }
+    }
     lastProbe = probe;
     if (probe.ok) {
       forgeReady = true;
       return true;
     }
     if (debug) console.error(`[forge-dsh] forge probe failed: ${probe.error}`);
-    if (agent != null && !noticedAgents.has(agent)) {
-      noticedAgents.add(agent);
-      try {
-        await agent.inject?.(pluginMessage(missingForgeNotice(probe.error)));
-      } catch {
-        // a throwing (or rejecting) inject must never interrupt session start
-      }
+    const state = startStateOf(agent);
+    if (state !== undefined && !state.noticed) {
+      state.noticed = true;
+      state.pending.push(missingForgeNotice(probe.error));
     }
     return false;
   };
@@ -130,30 +197,73 @@ function apply(ctx, config = {}) {
 
   // UserPromptSubmit — the prompt rides the step's claimed messages.
   ctx.effect(() => ctx.on("agent/pre-step", async (payload, next) => {
+    const state = startStateOf(payload?.agent);
+    const startWait = waitStart(state);
     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);
+    let decision;
+    if (commands.length === 0) {
+      decision = await next();
+    } else {
+      const eventPayload = buildEventPayload("UserPromptSubmit", payload?.agent, {
+        prompt: promptText(payload?.messages),
+      });
+      const outcome = await runHookGroup(commands, eventPayload, opts);
+      noteErrors("pre-step", outcome);
+      decision = await preStepDecision(outcome, next, payload?.agent);
+    }
+    await startWait;
+    if (state === undefined) return decision;
+    // a reject keeps the queue for the next pre-step; only an enter clears it
+    const delivery = prependStartContexts(decision, state.pending);
+    if (delivery.delivered) state.pending.length = 0;
+    return delivery.decision;
   }), "forge: pre-step");
 
-  // SessionStart — emit mode: detached, contexts queued via agent.inject.
+  // SessionStart — emit mode: detached, contexts queued per agent and
+  // delivered by the next pre-step (see startStates above).
   // 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 () => {
-      await ensureForge(agent);
+    const state = startStateOf(agent);
+    const queue = (outcome) => {
+      if (state !== undefined) {
+        // overlapping starts must not stack the same onboarding twice
+        for (const text of outcome.contexts) if (!state.pending.includes(text)) state.pending.push(text);
+      } else if (debug && outcome.contexts.length > 0) {
+        console.error("[forge-dsh] session-start contexts dropped: no agent handle to queue them on");
+      }
+    };
+    const run = (async () => {
+      const forgeOk = await ensureForge(agent);
+      // The bundled binary is not on PATH while forge's gate messages say
+      // `forge task …`, so the agent is told where it is. After a compaction the
+      // earlier hint is summarised away, so it is re-sent.
+      if (source === "compact" && state !== undefined) state.hinted = false;
+      if (forgeOk && binSource === "bundled" && state !== undefined && !state.hinted) {
+        state.hinted = true;
+        state.pending.push(bundledForgeHint(opts.forgeBin));
+      }
       const start = await runHookGroup(
         matchedCommands(spec.SessionStart, ""),
         buildEventPayload("SessionStart", agent, { source }),
         opts,
       );
       noteErrors("session-start", start);
-      sessionStartOutcome(start, agent);
+      queue(start);
+      // Welcome — queue order: welcome, path hint, forge's own contexts. One
+      // human-facing line per session: startup only (resume/compact are not a
+      // first meeting), never for delegated children (they report to their
+      // parent), and only when forge itself announced the project as managed —
+      // a working binary alone does not mean the gates apply here (no `forge
+      // init`, or `forge off`).
+      const isStartup = source === undefined || source === "startup";
+      const managed = start.contexts.some((text) => text.includes(MANAGED_BANNER));
+      if (forgeOk && welcome && isStartup && managed && !isSubagent(agent) && state !== undefined && !state.welcomed) {
+        state.welcomed = true;
+        const forgeVersion = (lastProbe?.version?.match(/\d+\.\d+\.\d+/) ?? [])[0];
+        state.pending.unshift(welcomeText(pluginVersion, forgeVersion));
+      }
       if (source === "compact") {
         const compact = await runHookGroup(
           matchedCommands(spec.PostCompact, ""),
@@ -161,11 +271,16 @@ function apply(ctx, config = {}) {
           opts,
         );
         noteErrors("post-compact", compact);
-        sessionStartOutcome(compact, agent);
+        queue(compact);
       }
     })().catch((error) => {
       if (debug) console.error(`[forge-dsh] session-start failed open: ${error}`);
     });
+    // overlapping session-starts (startup then compact) both gate the pre-step
+    if (state !== undefined) {
+      state.waited = false;
+      state.ready = Promise.all([state.ready, run]);
+    }
   }), "forge: session-start");
 
   // Stop — a blocking gate steers the agent into another step.
@@ -222,7 +337,7 @@ function apply(ctx, config = {}) {
             : `FAILED — gates inactive (${lastProbe.error})`;
         return {
           kind: "success",
-          text: `# Forge quality gates\n\nforgeBin: ${opts.forgeBin}  timeoutMs: ${opts.timeoutMs}\nprobe: ${probeLine}\n\n## Wired groups\n${groups}\n\n## Verdict summary (last ${recentRuns.length} runs)\n  runs=${summary.runs}  blocked=${summary.blocked}  fail-open=${summary.failOpen}  contexts=${summary.contexts}\n\n## Recent runs (last 10)\n${runs}`,
+          text: `# Forge quality gates\n\nforgeBin: ${opts.forgeBin} (${binSource})  timeoutMs: ${opts.timeoutMs}\nprobe: ${probeLine}\n\n## Wired groups\n${groups}\n\n## Verdict summary (last ${recentRuns.length} runs)\n  runs=${summary.runs}  blocked=${summary.blocked}  fail-open=${summary.failOpen}  contexts=${summary.contexts}\n\n## Recent runs (last 10)\n${runs}`,
         };
       },
     }), "forge: status command");

package/lib/tools.js

@@ -196,3 +196,48 @@ export function pluginMessage(text) {
     source: { kind: "plugin:forge-quality" },
   };
 }
+
+/**
+ * The marker forge's own SessionStart hook (task-resume) prints when the
+ * project is managed — the same mechanical signal the user-level instruction
+ * block keys on (internal/skillgen/claudemd.go). The welcome line is only
+ * truthful when it appeared, so the plugin waits for it instead of guessing from
+ * "forge --version runs".
+ *
+ * forge 自己的 SessionStart hook 在项目被接管时输出的横幅标记，与用户级指令段的
+ * 激活判据同源；欢迎语只在它出现时才属实。
+ */
+export const MANAGED_BANNER = "[forge-session]";
+
+/**
+ * Whether a DSH agent handle is a delegated child (its session header carries
+ * origin 'subagent' / a parentSession). Children report to their parent, not to
+ * the user, so they must not be told to greet anyone.
+ *
+ * @param {object|undefined} agent
+ * @returns {boolean}
+ */
+export function isSubagent(agent) {
+  const header = agent?.session?.header;
+  return header?.origin === "subagent" || header?.parentSession !== undefined;
+}
+
+/**
+ * First-turn onboarding line (model-facing; the user only sees what the model
+ * relays, so it asks for one sentence in the first reply). Carries the plugin
+ * and forge versions so a stale install is visible at a glance.
+ *
+ * 首轮引导：模型可见、用户只能通过模型复述看到，所以明确要求在第一次回复里
+ * 用一句话告知用户；带插件与 forge 版本，装旧版一眼可见。
+ *
+ * @param {string} pluginVersion
+ * @param {string|undefined} forgeVersion
+ * @returns {string}
+ */
+export function welcomeText(pluginVersion, forgeVersion) {
+  const versions = `插件 ${pluginVersion}${forgeVersion === undefined ? "" : `，forge ${forgeVersion}`}`;
+  return (
+    `[forge-dsh] Forge 质量门禁已接管本项目（${versions}）：修改源码前需先建 forge task，危险的 Bash 命令会被拦截。` +
+    "请在本会话第一次回复的末尾用一句话告知用户这一点，并提示：/forge-status 查看状态，forge off 关闭门禁。只提这一次。"
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent_forge/forge-dsh",
-  "version": "1.80.1",
+  "version": "1.82.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",
@@ -13,6 +13,7 @@
   "files": [
     "lib/index.js",
     "lib/runner.js",
+    "lib/bundled.js",
     "lib/decisions.js",
     "lib/tools.js",
     "lib/spec.json",
@@ -35,6 +36,9 @@
     "ai-code-quality"
   ],
   "license": "Apache-2.0",
+  "dependencies": {
+    "@agent_forge/forge": "1.82.0"
+  },
   "engines": {
     "node": ">=18"
   },