@agent_forge/forge-dsh 1.81.0 → 1.83.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,13 @@ 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)
+    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
 ```
@@ -101,37 +118,77 @@ 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
 next session probes again and gating resumes.
 
-Two latency trade-offs to know: hooks run **serially** per event (up to six 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.
-
-`/forge-status` reports 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.
+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 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)`).
+- **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
 
 ```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,70 @@
+/**
+ * @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;
+  }
+}

package/lib/decisions.js

@@ -18,7 +18,7 @@
  * @module decisions
  */
 
-import { runForgeHook } from "./runner.js";
+import { runForgeBatch, runForgeHook } from "./runner.js";
 import { pluginMessage } from "./tools.js";
 
 /**
@@ -26,6 +26,7 @@ import { pluginMessage } from "./tools.js";
  * @property {{reason: string, command: string}|undefined} blocked
  * @property {string[]} contexts - allow-path additionalContext, in order.
  * @property {string[]} errors   - fail-open infrastructure notes.
+ * @property {number} [durationMs] - wall time of the group run (for /forge-status).
  */
 
 /**
@@ -39,7 +40,8 @@ import { pluginMessage } from "./tools.js";
  */
 export async function runHookGroup(commands, payload, opts = {}) {
   const run = opts.runner ?? runForgeHook; // DI seam for tests
-  const outcome = { blocked: undefined, contexts: [], errors: [] };
+  const started = Date.now();
+  const outcome = { blocked: undefined, contexts: [], errors: [], durationMs: 0 };
   for (const command of commands) {
     const verdict = await run(command, payload, opts);
     if (verdict.error !== undefined) outcome.errors.push(`${command}: ${verdict.error}`);
@@ -49,6 +51,131 @@ export async function runHookGroup(commands, payload, opts = {}) {
     }
     if (verdict.context !== undefined) outcome.contexts.push(verdict.context);
   }
+  outcome.durationMs = Date.now() - started;
+  return outcome;
+}
+
+/**
+ * Status-only receipts forge prints when it has nothing to say ("no weakening
+ * detected", "all skills SAFE", "no .mcp.json" …). The host injects every
+ * allow-path context into the conversation as a synthetic user message, so each
+ * of these costs the model a turn-sized distraction for zero information. Only
+ * receipts confirmed to carry no instruction are listed; an allowlist of "what
+ * the model must see" would silently drop any new advisory, so unknown notes
+ * pass through. A note that tells anyone to DO something carries `Advisory:` or
+ * is a directive and never matches here.
+ *
+ * forge 在「无事可报」时输出的纯状态回执。宿主把 allow 路径的上下文注入成合成 user
+ * 消息，每条都白白占用模型一次注意力。只列已确认不含任何指令的回执；未知的一律放行
+ * （白名单会静默吞掉新增的 advisory）。要求任何人做事的提示带 `Advisory:` 或是指令，
+ * 不会命中这里。
+ */
+const QUIET_NOTES = [
+  /^\[assertion-check\] no weakening detected/,
+  /^\[auto-compile\] (?:no source touched|research-mode session)/,
+  /^\[skill-scan\] (?:all skills SAFE|no ~\/\.claude\/skills)/,
+  /^\[mcp-scan\] (?:no |\.mcp\.json unreadable|项目级 \.mcp\.json 无 config 层风险信号)/,
+  /^\[workflow-test-guard\] workflow 配置变更后 internal\/ci 守护测试全绿/,
+];
+
+/**
+ * Remove the quiet receipts from one context string. Judged per paragraph (a
+ * batch merges the group's contexts with a blank line between them); a paragraph
+ * is quiet when its first line matches. Returns "" when nothing is left.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function dropQuietNotes(text) {
+  return text
+    .split("\n\n")
+    .filter((paragraph) => !QUIET_NOTES.some((re) => re.test(paragraph)))
+    .join("\n\n");
+}
+
+/**
+ * Marks an outcome error as "this group ran per hook instead of batched" — the
+ * run still executed its gates, so it is a performance note, not a lost run, and
+ * the fail-open counter must not count it (index.js reads this prefix).
+ */
+export const BATCH_DOWNGRADE_MARK = "[batch→per-hook]";
+
+/** Consecutive unexplained batch failures of one group before batch is switched off for the process. */
+const BATCH_FAIL_LIMIT = 3;
+
+/** How long a group that timed out as a batch stays per-hook before batch is tried on it again. */
+const SLOW_RETRY_MS = 10 * 60 * 1000;
+
+/**
+ * Run the matched spec groups of one event — one `forge hook batch` process per
+ * group instead of one process per hook (the spec's matcher only SELECTS the
+ * group; forge owns the roster).
+ *
+ * Fail-open stays the invariant, with one guard: a batch that cannot answer is
+ * never taken as an allow. An error verdict ("exited with code 2 and no output"
+ * is what an older forge prints on a block) re-runs THAT group per hook — the
+ * legacy path whose contract every forge version honours. Two kinds of failure:
+ *   - a timeout: batch gives the whole group ONE ceiling, so a single hung hook
+ *     would starve every gate behind it. The group is re-run per hook (each hook
+ *     gets its own ceiling again) and stays per-hook for SLOW_RETRY_MS, so a
+ *     persistently slow group costs one stall, not one per tool call, while a
+ *     one-off hiccup (cold start, a virus scan) is not held against it forever;
+ *   - anything else: re-run per hook this once. Only BATCH_FAIL_LIMIT failures of
+ *     the SAME group in a row switch batch off for the process (a healthy group
+ *     must not keep resetting another group's streak); one success of that group
+ *     resets it, so a transient spawn error does not slow every later call.
+ * The re-run can execute hooks the batch already ran; observation-only hooks are
+ * de-duplicated by forge's idempotency window, blocking hooks simply run again.
+ *
+ * `opts.batch === false` forces per-hook from the start.
+ *
+ * @param {string} event - forge event name.
+ * @param {Array<{matcher: string, commands: string[]}>} groups - matched spec groups, spec order.
+ * @param {object} payload - Claude-Code-shape stdin payload.
+ * @param {object} [opts] - forgeBin/timeoutMs plus test seams `batchRunner`, `runner`, `batchState`.
+ * @returns {Promise<GroupOutcome>}
+ */
+export async function runMatchedGroups(event, groups, payload, opts = {}) {
+  const started = Date.now();
+  const batchRun = opts.batchRunner ?? runForgeBatch; // DI seam for tests
+  const state = opts.batchState ?? { broken: false };
+  state.slow ??= new Map(); // label -> when it timed out
+  state.failStreaks ??= new Map(); // label -> consecutive failures
+  const outcome = { blocked: undefined, contexts: [], errors: [], durationMs: 0 };
+  for (const group of groups) {
+    const label = `batch ${event}${group.matcher === "" ? "" : `/${group.matcher}`}`;
+    let part;
+    const slowSince = state.slow.get(label);
+    const isSlow = slowSince !== undefined && Date.now() - slowSince < SLOW_RETRY_MS;
+    if (opts.batch !== false && !state.broken && !isSlow) {
+      const verdict = await batchRun(event, group.matcher, payload, opts);
+      if (verdict.error === undefined) {
+        state.failStreaks.delete(label);
+        state.slow.delete(label);
+        part = {
+          blocked: verdict.block ? { reason: verdict.reason ?? "denied", command: label } : undefined,
+          contexts: verdict.context === undefined ? [] : [verdict.context],
+          errors: [],
+        };
+      } else if (verdict.timedOut === true) {
+        state.slow.set(label, Date.now());
+        outcome.errors.push(`${BATCH_DOWNGRADE_MARK} ${label}: ${verdict.error} — running this group's hooks one by one so a hung hook cannot starve the gates behind it`);
+      } else {
+        const streak = (state.failStreaks.get(label) ?? 0) + 1;
+        state.failStreaks.set(label, streak);
+        if (streak >= BATCH_FAIL_LIMIT) state.broken = true;
+        outcome.errors.push(`${BATCH_DOWNGRADE_MARK} ${label}: ${verdict.error} — running this group's hooks one by one`);
+      }
+    }
+    if (part === undefined) part = await runHookGroup(group.commands, payload, opts);
+    outcome.errors.push(...part.errors);
+    outcome.contexts.push(...part.contexts.map(dropQuietNotes).filter((text) => text !== ""));
+    if (part.blocked !== undefined) {
+      outcome.blocked = part.blocked;
+      break;
+    }
+  }
+  outcome.durationMs = Date.now() - started;
   return outcome;
 }
 
@@ -158,16 +285,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,39 @@
  * @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)
+ *   locale    - language of the plugin's own messages: "en" | "zh" | "auto"
+ *               (default auto: env FORGE_DSH_LOCALE, then the system locale)
+ *   checkLatest - false stops /forge-status from asking the registry for the latest plugin
+ *               version (default true; one read-only GET, only when the command runs)
+ *   registry  - registry /forge-status asks (default https://registry.npmjs.org)
+ *   skillsHome - home directory whose .agents/skills is checked for the skill library
+ *               (default: the user's home; a seam for tests)
+ *   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 { resolveBundledForge } from "./bundled.js";
+import { compareVersions, fetchLatestVersion, isPlainVersion } from "./latest.js";
+import { messagesFor, resolveLocale } from "./messages.js";
+import { agentsSkillsInstalled } from "./skills.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 { BATCH_DOWNGRADE_MARK, runMatchedGroups, preExecuteDecision, postExecuteDecision, preStepDecision, prependStartContexts, turnStoppingOutcome } from "./decisions.js";
+import { buildEventPayload, buildToolPayload, matchedGroups, pluginMessage, promptText, toCCToolName, 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;
+
+/** Fail-open runs in one session before the degraded advisory fires. */
+const DEGRADED_AFTER = 3;
 
 /** Stable Cordis plugin name. */
 const name = "forge-quality";
@@ -45,20 +66,53 @@ 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,
+    // One `forge hook batch` process per matcher group instead of one per hook (~half the
+    // per-tool-call latency). Config `batch`: true forces it, false forces the per-hook path,
+    // unset = auto — on only once the probe shows a forge of the plugin's own version. Batch asks
+    // forge to select the group by the plugin's matcher string, and an older or newer forge may
+    // not agree (an unmatched matcher is a silent empty allow, and forges before the stdout fix
+    // print nothing on a block), so a mismatched forge stays on the per-hook path, which only
+    // depends on hook names. Runtime failures degrade per call (see runMatchedGroups).
+    batch: config.batch === true,
+    batchState: { broken: false },
   };
+  const batchMode = config.batch === true ? "forced" : config.batch === false ? "off" : "auto";
   const debug = config.debug === true;
+  const welcome = config.welcome !== false;
+  let skillsOffered = false;
+  const msg = messagesFor(resolveLocale(config.locale));
+  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 = [];
-  const noteErrors = (label, outcome) => {
+  const noteErrors = (label, outcome, agent) => {
+    // Per-session count of runs that lost their feedback to fail-open — the signal behind the
+    // one-time degraded advisory at Stop. The batch->per-hook downgrade note is not a lost run
+    // (the serial retry ran the gate), so it does not count.
+    // And nothing is counted while forge itself is missing: that is the missing-CLI notice's job,
+    // and "raise timeoutMs" would be the wrong advice.
+    const lost = lastProbe?.ok !== false && outcome.errors.some((e) => !e.startsWith(BATCH_DOWNGRADE_MARK));
+    const state = lost ? startStateOf(agent) : undefined;
+    if (state !== undefined) state.failOpen = (state.failOpen ?? 0) + 1;
     recentRuns.push({
       label,
       blocked: outcome.blocked?.command ?? null,
       contexts: outcome.contexts.length,
       errors: outcome.errors,
+      ms: outcome.durationMs ?? 0,
       at: Date.now(),
     });
     if (recentRuns.length > 50) recentRuns.shift();
@@ -67,23 +121,56 @@ 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; " +
-    "if it lives elsewhere, set forgeBin in the profile patch." +
-    (error === undefined ? "" : `\nProbe error: ${error}`);
   const ensureForge = async (agent) => {
     if (forgeReady) return true;
     if (probeInFlight === undefined) {
@@ -92,92 +179,169 @@ 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;
+      if (batchMode === "auto") opts.batch = (probe.version?.match(/\d+\.\d+\.\d+/) ?? [])[0] === pluginVersion;
       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(msg.missingForge(opts.forgeBin, probe.error));
     }
     return false;
   };
 
   // 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);
+    const groups = matchedGroups(spec.PreToolUse, toCCToolName(exec?.name ?? ""));
+    if (groups.length === 0) return next();
+    const outcome = await runMatchedGroups("PreToolUse", groups, buildToolPayload(exec, "PreToolUse"), opts);
+    noteErrors("pre-execute", outcome, exec?.agent);
     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);
+    const groups = matchedGroups(spec.PostToolUse, toCCToolName(exec?.name ?? ""));
+    if (groups.length === 0) return next();
+    const outcome = await runMatchedGroups("PostToolUse", groups, buildToolPayload(exec, "PostToolUse"), opts);
+    noteErrors("post-execute", outcome, exec?.agent);
     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);
+    const state = startStateOf(payload?.agent);
+    const startWait = waitStart(state);
+    const groups = matchedGroups(spec.UserPromptSubmit, "");
+    let decision;
+    if (groups.length === 0) {
+      decision = await next();
+    } else {
+      const eventPayload = buildEventPayload("UserPromptSubmit", payload?.agent, {
+        prompt: promptText(payload?.messages),
+      });
+      const outcome = await runMatchedGroups("UserPromptSubmit", groups, eventPayload, opts);
+      noteErrors("pre-step", outcome, payload?.agent);
+      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 start = await runHookGroup(
-        matchedCommands(spec.SessionStart, ""),
+    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(msg.bundledHint(opts.forgeBin));
+      }
+      const start = await runMatchedGroups(
+        "SessionStart",
+        matchedGroups(spec.SessionStart, ""),
         buildEventPayload("SessionStart", agent, { source }),
         opts,
       );
-      noteErrors("session-start", start);
-      sessionStartOutcome(start, agent);
+      noteErrors("session-start", 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(msg.welcome(pluginVersion, forgeVersion));
+        // The plugin brings the bridge and the forge CLI, not the skill library DSH reads from
+        // ~/.agents/skills; offer it (right behind the welcome) when that directory is empty.
+        // Once per plugin instance: there is no persisted "declined", so asking again at every
+        // new session would nag a user who already said no.
+        if (!skillsOffered && !agentsSkillsInstalled(config.skillsHome)) {
+          skillsOffered = true;
+          state.pending.splice(1, 0, msg.skillsHint(opts.forgeBin));
+        }
+      }
       if (source === "compact") {
-        const compact = await runHookGroup(
-          matchedCommands(spec.PostCompact, ""),
+        const compact = await runMatchedGroups(
+          "PostCompact",
+          matchedGroups(spec.PostCompact, ""),
           buildEventPayload("PostCompact", agent, {}),
           opts,
         );
-        noteErrors("post-compact", compact);
-        sessionStartOutcome(compact, agent);
+        noteErrors("post-compact", 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.
   ctx.effect(() => ctx.on("agent/turn-stopping", async (payload) => {
     const agent = payload?.agent;
-    const outcome = await runHookGroup(
-      matchedCommands(spec.Stop, ""),
+    const outcome = await runMatchedGroups(
+      "Stop",
+      matchedGroups(spec.Stop, ""),
       buildEventPayload("Stop", agent, { stop_hook_active: false }),
       opts,
     );
-    noteErrors("turn-stopping", outcome);
-    return turnStoppingOutcome(outcome, agent);
+    noteErrors("turn-stopping", outcome, agent);
+    const steering = await turnStoppingOutcome(outcome, agent);
+    // Fail-open is silent by design, so a session where gates keep timing out looks healthy while
+    // checking nothing. Once per session, at the first Stop that is not already steering for a
+    // real block, say so (advisory — it blocks nothing). The count is per session, not global.
+    const state = startStateOf(agent);
+    if (outcome.blocked === undefined && state !== undefined && (state.failOpen ?? 0) >= DEGRADED_AFTER && !state.degradedNoted) {
+      state.degradedNoted = true;
+      agent?.steer?.(pluginMessage(msg.degraded(state.failOpen)));
+    }
+    return steering;
   }), "forge: turn-stopping");
 
   // /forge-status — wired groups + verdict summary + recent runs (the only
@@ -212,9 +376,45 @@ function apply(ctx, config = {}) {
               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}`);
+              parts.push(`${r.ms}ms`);
               if (r.errors.length > 0) parts.push(`FAIL-OPEN: ${r.errors.join("; ")}`);
               return parts.join("  ");
             }).join("\n");
+        // Per-interception-point wall time over the ring buffer: the number behind "why is every
+        // tool call slow" (one batch spawn per group should sit well under the per-hook sum).
+        const byLabel = new Map();
+        for (const r of recentRuns) {
+          const t = byLabel.get(r.label) ?? { runs: 0, total: 0, max: 0 };
+          t.runs += 1;
+          t.total += r.ms;
+          t.max = Math.max(t.max, r.ms);
+          byLabel.set(r.label, t);
+        }
+        const timing = byLabel.size === 0
+          ? "  (no hook runs yet)"
+          : [...byLabel].map(([label, t]) => `  ${label}  runs=${t.runs}  avg=${Math.round(t.total / t.runs)}ms  max=${t.max}ms`).join("\n");
+        const forgeVersion = (lastProbe?.version?.match(/\d+\.\d+\.\d+/) ?? [])[0];
+        const slowGroups = opts.batchState.slow === undefined ? [] : [...opts.batchState.slow.keys()];
+        let dispatchLine;
+        if (batchMode === "off") dispatchLine = "per-hook (batch:false)";
+        else if (opts.batchState.broken) dispatchLine = "per-hook (batch failed three times in a row; restart the host to retry)";
+        else if (!opts.batch) {
+          dispatchLine = lastProbe === undefined
+            ? "per-hook (waiting for the first session start to check the forge version)"
+            : `per-hook (forge ${forgeVersion ?? "of unknown version"} != plugin ${pluginVersion}: batch needs a forge of the plugin's own version)`;
+        } else dispatchLine = "batch (one forge process per matcher group)";
+        if (slowGroups.length > 0) dispatchLine += `; per-hook for slow group${slowGroups.length > 1 ? "s" : ""}: ${slowGroups.join(", ")}`;
+        let latestLine;
+        if (config.checkLatest === false) {
+          latestLine = "not checked (checkLatest:false)";
+        } else {
+          const latest = await (config.fetchLatest ?? (() => fetchLatestVersion({ registry: config.registry })))();
+          // an injected or misbehaving source may hand back anything: only plain semver is shown
+          if (latest === undefined || !isPlainVersion(latest)) latestLine = "unknown (offline, or the registry did not answer)";
+          else if (compareVersions(pluginVersion, latest) === -1) {
+            latestLine = `${latest} — a newer plugin is published; an old install keeps working but misses fixes, so update it`;
+          } else latestLine = `${latest} (up to date)`;
+        }
         const probeLine = lastProbe === undefined
           ? "not run yet (no session start in this process)"
           : lastProbe.ok
@@ -222,7 +422,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\nplugin: ${pluginVersion}  latest: ${latestLine}\nforgeBin: ${opts.forgeBin} (${binSource})  timeoutMs: ${opts.timeoutMs}\ndispatch: ${dispatchLine}\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## Timing per interception point (last ${recentRuns.length} runs)\n${timing}\n\n## Recent runs (last 10)\n${runs}`,
         };
       },
     }), "forge: status command");

package/lib/latest.js

@@ -0,0 +1,90 @@
+/**
+ * @agent_forge/forge-dsh — "is a newer plugin published?" for /forge-status.
+ *
+ * Version drift between an installed plugin and the repo is silent: an old
+ * install keeps working while missing fixes (the audit found a 1.74.1 install
+ * lacking everything since). /forge-status is the one place the user looks when
+ * something seems off, so it asks the registry once, with a short timeout, and
+ * shows the answer. It is a read-only GET issued only when the user runs the
+ * command, never at session start, and every failure (offline, private registry,
+ * odd response) degrades to "unknown" — a status command must not throw.
+ *
+ * 已装插件与仓库的版本漂移是静默的：旧版一直能用，只是缺修复（审计里 1.74.1 的装机就缺了
+ * 此后的一切）。/forge-status 是用户觉得不对劲时唯一会看的地方，所以在这里问一次 registry
+ * （短超时）并展示结果。只在用户执行该命令时发一次只读 GET，绝不在会话启动时发；任何失败
+ * （离线、私有 registry、响应异常）都降级为「未知」——状态命令不能抛错。
+ *
+ * @module latest
+ */
+
+const DEFAULT_REGISTRY = "https://registry.npmjs.org";
+const PACKAGE_PATH = "@agent_forge%2Fforge-dsh";
+
+/** A published plugin version: plain semver, optionally with a pre-release/build tag, bounded length. */
+const PLAIN_VERSION = /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]{1,40})?$/;
+
+/**
+ * Whether a string is safe to show as a version. The registry's answer ends up in
+ * /forge-status text, which the model can read, so anything that is not plain semver
+ * (newlines, escape sequences, prose) is refused rather than echoed.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isPlainVersion(value) {
+  return typeof value === "string" && value.length <= 64 && PLAIN_VERSION.test(value);
+}
+
+/**
+ * Compare the numeric core (major.minor.patch) of two versions. A pre-release
+ * suffix is ignored; an unparseable input has no order.
+ *
+ * @param {string|undefined} a
+ * @param {string|undefined} b
+ * @returns {-1|0|1|undefined} negative when a is older than b.
+ */
+export function compareVersions(a, b) {
+  const core = (v) => {
+    const m = /^(\d+)\.(\d+)\.(\d+)/.exec(String(v ?? ""));
+    return m === null ? undefined : [Number(m[1]), Number(m[2]), Number(m[3])];
+  };
+  const left = core(a);
+  const right = core(b);
+  if (left === undefined || right === undefined) return undefined;
+  for (let i = 0; i < 3; i += 1) {
+    if (left[i] !== right[i]) return left[i] < right[i] ? -1 : 1;
+  }
+  return 0;
+}
+
+/**
+ * The registry's latest published plugin version, or undefined on any failure.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.registry="https://registry.npmjs.org"]
+ * @param {number} [opts.timeoutMs=3000]
+ * @param {typeof fetch} [opts.fetch] - injected for tests; defaults to the global fetch.
+ * @param {boolean} [opts.noGlobalFetch] - tests: pretend the runtime has no fetch.
+ * @returns {Promise<string|undefined>}
+ */
+export async function fetchLatestVersion(opts = {}) {
+  const doFetch = opts.fetch ?? (opts.noGlobalFetch ? undefined : globalThis.fetch);
+  if (typeof doFetch !== "function") return undefined;
+  const controller = new AbortController();
+  // Not unref'd: the timer is what ends a hung request, and `finally` clears it, so it can keep
+  // the process alive for at most timeoutMs. An unref'd timer lets the loop exit mid-request when
+  // nothing else is pending.
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs ?? 3000);
+  try {
+    // inside the try: a misconfigured registry value must not make /forge-status throw
+    const registry = String(opts.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, "");
+    const res = await doFetch(`${registry}/${PACKAGE_PATH}/latest`, { signal: controller.signal });
+    if (!res?.ok) return undefined;
+    const body = await res.json();
+    return isPlainVersion(body?.version) ? body.version : undefined;
+  } catch {
+    return undefined;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/lib/messages.js

@@ -0,0 +1,110 @@
+/**
+ * @agent_forge/forge-dsh — model-facing message catalogue.
+ *
+ * Every line the plugin itself puts into the conversation lives here, in both
+ * languages, so the wording of one session is uniform (the old mix: English
+ * missing-CLI notice, Chinese welcome) and a new message cannot ship in one
+ * language only — a test pins that the two catalogues have the same keys.
+ * forge's own hook texts are not translated here; they come from the forge binary.
+ *
+ * Language: config `locale` > env FORGE_DSH_LOCALE > the system locale. A value that
+ * names no supported language is skipped; with nothing usable the result is English.
+ *
+ * 插件自己写进对话的每一句话都集中在此，中英各一份：同一会话措辞统一（此前缺 CLI 提示
+ * 是英文、欢迎语是中文），且新增消息不可能只有一种语言——测试钉住两份目录键集合相同。
+ * forge 自己 hook 的文案由 forge 二进制输出，不在此翻译。
+ * 语言：配置 locale > 环境变量 FORGE_DSH_LOCALE > 系统 locale；不支持的一律回落英文。
+ *
+ * @module messages
+ */
+
+/** Supported catalogue languages. */
+const LOCALES = new Set(["en", "zh"]);
+
+/**
+ * Pick the catalogue language.
+ *
+ * @param {string|undefined} configured - the profile patch's `locale` ("en" | "zh" | "auto").
+ * @param {Record<string, string|undefined>} [env] - process.env override (tests).
+ * @param {() => string} [systemLocale] - system locale tag source (tests).
+ * @returns {"en"|"zh"}
+ */
+export function resolveLocale(
+  configured,
+  env = process.env,
+  systemLocale = () => Intl.DateTimeFormat().resolvedOptions().locale,
+) {
+  // Tags are normalized (zh-CN, zh_CN, ZH, zh-Hans all mean zh). A value that names no supported
+  // language — a typo, "auto", a language we have no catalogue for — does not decide anything and
+  // falls through to the next source, so a bad config line cannot mask FORGE_DSH_LOCALE or the system.
+  for (const candidate of [configured, env.FORGE_DSH_LOCALE]) {
+    const language = String(candidate ?? "").trim().toLowerCase().replace(/_/g, "-").split("-")[0];
+    if (LOCALES.has(language)) return language;
+  }
+  try {
+    return systemLocale().toLowerCase().startsWith("zh") ? "zh" : "en";
+  } catch {
+    return "en";
+  }
+}
+
+const quoted = (path) => (/\s/.test(path) ? `"${path}"` : path);
+
+const en = {
+  /** One first-turn line; the user only sees what the model relays, hence the explicit ask. */
+  welcome: (pluginVersion, forgeVersion) =>
+    `[forge-dsh] Forge quality gates now govern this project (plugin ${pluginVersion}${forgeVersion === undefined ? "" : `, forge ${forgeVersion}`}): ` +
+    "create a forge task before editing source, and dangerous Bash commands are intercepted. " +
+    "In your first reply, tell the user this in one sentence and mention /forge-status for status and `forge off` to switch the gates off. Say it only once.",
+  /** The bundled binary is not on PATH while forge's gate messages say `forge task …`. */
+  bundledHint: (binPath) =>
+    `[forge-dsh] forge CLI bundled with this plugin: ${quoted(binPath)}. 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`.",
+  /** Installing writes the user's home (~/.agents/skills), hence "after the user agrees". */
+  skillsHint: (forgeBin) =>
+    "[forge-dsh] Forge's skill library is not installed for DSH (~/.agents/skills is empty), so the skills forge hooks point to are unavailable. " +
+    "Offer to install it, and run `" + quoted(forgeBin) + " skills install --global --target agents` only after the user agrees.",
+  missingForge: (forgeBin, error) =>
+    `[forge-dsh] forge CLI not found (forgeBin: ${forgeBin}). ` +
+    "Forge gates are OFF for this session — every action runs unguarded (fail-open). " +
+    "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}`),
+  degraded: (count) =>
+    `[forge-dsh] ${count} forge hook runs failed open in this session (a timeout or an unreadable forge reply), so those checks did not run. ` +
+    "Run /forge-status to see which, and raise timeoutMs if a gate is timing out. This is advisory; nothing is blocked.",
+};
+
+const zh = {
+  welcome: (pluginVersion, forgeVersion) =>
+    `[forge-dsh] Forge 质量门禁已接管本项目（插件 ${pluginVersion}${forgeVersion === undefined ? "" : `，forge ${forgeVersion}`}）：修改源码前需先建 forge task，危险的 Bash 命令会被拦截。` +
+    "请在本会话第一次回复的末尾用一句话告知用户这一点，并提示：/forge-status 查看状态，forge off 关闭门禁。只提这一次。",
+  bundledHint: (binPath) =>
+    `[forge-dsh] 本插件自带的 forge CLI：${quoted(binPath)}。它可能不在 PATH 上——` +
+    "当门禁消息或协议要求你运行 `forge …` 命令时，请用这个路径代替 `forge`。",
+  skillsHint: (forgeBin) =>
+    "[forge-dsh] 尚未为 DSH 安装 Forge 技能库（~/.agents/skills 为空），forge hook 提示的 skill 因此不可用。" +
+    "请向用户提议安装，征得用户同意后再运行 `" + quoted(forgeBin) + " skills install --global --target agents`。",
+  missingForge: (forgeBin, error) =>
+    `[forge-dsh] 未找到 forge CLI（forgeBin：${forgeBin}）。` +
+    "本会话 Forge 门禁处于关闭状态——所有操作都不受保护（fail-open）。" +
+    "请重装本插件（它自带 forge）或运行 `npm install -g @agent_forge/forge`，然后开启新会话；" +
+    "如果 forge 在别处，请在 profile patch 里设置 forgeBin。" +
+    (error === undefined ? "" : `\n探测错误：${error}`),
+  degraded: (count) =>
+    `[forge-dsh] 本会话有 ${count} 次 forge hook 运行 fail-open（超时或 forge 回复无法解析），这些检查没有执行。` +
+    "运行 /forge-status 查看是哪些，若某个门禁超时请调大 timeoutMs。这只是提示，不会阻断任何操作。",
+};
+
+const CATALOGUES = { en, zh };
+
+/**
+ * The message catalogue for a language; unknown languages get English.
+ *
+ * @param {string} locale
+ * @returns {typeof en}
+ */
+export function messagesFor(locale) {
+  return CATALOGUES[locale] ?? en;
+}

package/lib/runner.js

@@ -27,6 +27,7 @@ import { spawn } from "node:child_process";
  * @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).
+ * @property {boolean} [timedOut] - the failure was the ceiling kill (not a forge error).
  */
 
 /**
@@ -39,7 +40,8 @@ import { spawn } from "node:child_process";
  * and EVERY gate silently fails open. cmd.exe resolves forge.cmd via PATHEXT
  * (and a bare forge.exe directly), so win32 routes through it. argv holds
  * spec constants only (safe charset). The binary is operator config and is
- * quoted, never escaped — see the metacharacter note inside planSpawn.
+ * quoted, never escaped — see the metacharacter note inside planSpawn. Arguments
+ * with a cmd metacharacter (a batch matcher such as Write|Edit) are quoted too.
  *
  * @param {string} forgeBin - binary name/path from config.
  * @param {string[]} argv - hook arguments (spec constants).
@@ -56,9 +58,11 @@ export function planSpawn(forgeBin, argv, platform = process.platform) {
   // %VAR% expansion (cmd expands it even inside quotes) and ! with delayed
   // expansion (off by default). Both are accepted residual risk because
   // forgeBin is trusted operator config — the same trust level as PATH itself.
-  const needsQuotes = /[&|()<>^,;=\s]/.test(forgeBin);
-  const file = needsQuotes && !forgeBin.includes('"') ? `"${forgeBin}"` : forgeBin;
-  return { file, args: argv, shell: true };
+  const quote = (token) => (/[&|()<>^,;=\s]/.test(token) && !token.includes('"') ? `"${token}"` : token);
+  // Arguments get the same treatment: a batch matcher like "Write|Edit" would
+  // otherwise be parsed by cmd.exe as a pipe. Spec-constant arguments (hook
+  // names, flags) carry no metacharacter and pass through unchanged.
+  return { file: quote(forgeBin), args: argv.map(quote), shell: true };
 }
 
 /**
@@ -73,10 +77,37 @@ export function planSpawn(forgeBin, argv, platform = process.platform) {
  * @returns {Promise<HookVerdict>}
  */
 export function runForgeHook(command, payload, opts = {}) {
+  const parts = command.split(" "); // ["forge","hook","task-guard"]
+  return runForge(parts.slice(1), payload, opts);
+}
+
+/**
+ * Run one whole matcher group in a single forge process:
+ * `forge hook batch --event <E> [--matcher <M>]`. forge runs the group's roster
+ * in order, stops at the first block, and prints that hook's decision JSON to
+ * stdout (same contract as a single hook); allow-path contexts come back merged
+ * into one document. One spawn instead of N saves the per-process start-up cost on
+ * every tool call. Forges from before the stdout fix print nothing on a block —
+ * decisions.runMatchedGroups detects that and falls back to per-hook runs.
+ *
+ * @param {string} event - forge event name (PreToolUse, Stop, …).
+ * @param {string} matcher - the spec group's matcher; "" selects the event's
+ *   matcher-less group.
+ * @param {object} payload - Claude-Code-shape hook stdin payload.
+ * @param {object} [opts] - same as runForgeHook.
+ * @returns {Promise<HookVerdict>}
+ */
+export function runForgeBatch(event, matcher, payload, opts = {}) {
+  const argv = ["hook", "batch", "--event", event];
+  if (matcher !== "") argv.push("--matcher", matcher);
+  return runForge(argv, payload, opts);
+}
+
+/** Spawn forge with `argv`, feed the payload, and fold stdout into a verdict. */
+function runForge(argv, payload, opts) {
   const forgeBin = opts.forgeBin ?? "forge";
   const timeoutMs = opts.timeoutMs ?? 30000;
-  const parts = command.split(" "); // ["forge","hook","task-guard"]
-  const plan = planSpawn(forgeBin, parts.slice(1));
+  const plan = planSpawn(forgeBin, argv);
   return new Promise((resolve) => {
     let child;
     try {
@@ -109,7 +140,7 @@ export function runForgeHook(command, payload, opts = {}) {
       if (settled) return;
       settled = true;
       killTree(child, plan.shell);
-      resolve({ block: false, error: `timeout after ${timeoutMs}ms` });
+      resolve({ block: false, error: `timeout after ${timeoutMs}ms`, timedOut: true });
     }, timeoutMs);
     const settle = (verdict) => {
       if (settled) return;

package/lib/skills.js

@@ -0,0 +1,38 @@
+/**
+ * @agent_forge/forge-dsh — is Forge's skill library installed for DSH?
+ *
+ * Installing the plugin delivers the bridge and (via its dependency) the forge
+ * CLI, but not the skill library: DSH reads the agent-neutral `~/.agents/skills`
+ * directory, which only `forge skills install --global --target agents` fills.
+ * Without it a DSH user silently gets half the product, so the first-turn
+ * onboarding offers the install when the directory is empty.
+ *
+ * 装插件交付的是桥接层和（经依赖）forge CLI，不含技能库：DSH 读跨 agent 的
+ * `~/.agents/skills`，只有 `forge skills install --global --target agents` 会填充它。
+ * 缺了它 DSH 用户悄悄只拿到半个产品，所以目录为空时首轮引导会提议安装。
+ *
+ * @module skills
+ */
+import { readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * Whether `<home>/.agents/skills` holds at least one entry (a link or a copy).
+ * A missing directory counts as not installed. Any other failure — an unreadable
+ * or odd location — degrades to `true`: this only gates a polite nudge, and
+ * nagging on an error the plugin cannot interpret would be worse than staying quiet.
+ *
+ * @param {string} [home] - home directory (tests); defaults to the user's.
+ * @param {(dir: string) => string[]} [readdir] - directory reader (tests); defaults to fs.readdirSync.
+ * @returns {boolean}
+ */
+export function agentsSkillsInstalled(home = homedir(), readdir = readdirSync) {
+  if (typeof home !== "string" || home === "") return true;
+  try {
+    // dotfiles (.DS_Store …) are not skills
+    return readdir(join(home, ".agents", "skills")).some((name) => !name.startsWith("."));
+  } catch (error) {
+    return error?.code !== "ENOENT";
+  }
+}

package/lib/tools.js

@@ -89,6 +89,27 @@ export function matchedCommands(groups, ccName) {
   return commands;
 }
 
+/**
+ * The spec groups of one event whose matcher accepts ccName, as
+ * `{matcher, commands}` in spec order. The matcher is what `forge hook batch
+ * --matcher` selects on ("" = the event's matcher-less group); `commands` is the
+ * same group's roster, kept for the serial fallback. Matching semantics are
+ * identical to matchedCommands.
+ *
+ * @param {Array<{matcher?: string, hooks: Array<{command: string}>}>} groups
+ * @param {string} ccName
+ * @returns {Array<{matcher: string, commands: string[]}>}
+ */
+export function matchedGroups(groups, ccName) {
+  const out = [];
+  for (const group of groups ?? []) {
+    const matcher = group.matcher ?? "";
+    if (matcher !== "" && !new RegExp(`^(?:${matcher})$`).test(ccName)) continue;
+    out.push({ matcher, commands: (group.hooks ?? []).map((hook) => hook.command) });
+  }
+  return out;
+}
+
 /**
  * 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
@@ -196,3 +217,28 @@ 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;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent_forge/forge-dsh",
-  "version": "1.81.0",
+  "version": "1.83.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,10 @@
   "files": [
     "lib/index.js",
     "lib/runner.js",
+    "lib/bundled.js",
+    "lib/messages.js",
+    "lib/skills.js",
+    "lib/latest.js",
     "lib/decisions.js",
     "lib/tools.js",
     "lib/spec.json",
@@ -35,6 +39,9 @@
     "ai-code-quality"
   ],
   "license": "Apache-2.0",
+  "dependencies": {
+    "@agent_forge/forge": "1.83.0"
+  },
   "engines": {
     "node": ">=18"
   },