forgedock 1.1.11 → 1.2.0

package/bin/hooks/pre-tool-use.mjs

@@ -92,13 +92,43 @@ async function getInvariants() {
  *    setting env vars via Bash tool calls, as this hook reads process.env which
  *    is set at process start, not at tool-call time).
  *
- * Both rules only apply inside a ForgeDock-managed directory (a directory
+ * 5. Filesystem-root `find` guard (issue #2034)
+ *    Intercepts any Bash command containing a `find` invocation whose search
+ *    root is `/` or a bare Git-Bash drive mount (`/c`, `/d`, ...) and
+ *    hard-blocks it. On Windows Git Bash, `/` spans every mounted drive, so a
+ *    root-anchored `find` never terminates and accumulates as an orphaned,
+ *    CPU-exhausting process once its parent sub-agent exits (issue #1984 was
+ *    a narrow, single-call-site precursor fix — this rule is the systemic,
+ *    deterministic follow-up). No override — a root-anchored `find` has no
+ *    legitimate use in any ForgeDock pipeline.
+ *
+ * 6. Attribution guard
+ *    Intercepts commit / PR / issue / comment creation commands (`git commit`,
+ *    `gh pr create|edit|comment`, `gh issue create|edit|comment`) and
+ *    hard-blocks any whose message or body carries the Claude Code harness
+ *    default attribution — "🤖 Generated with [Claude Code]", "Co-Authored-By:
+ *    Claude", or the `noreply@anthropic.com` co-author trailer. Pipeline output
+ *    is ForgeDock-branded; the assistant-tool attribution must never leak into
+ *    a repo's public commit/PR/issue history. The agent is told to remove the
+ *    attribution and, where a footer is wanted, use the ForgeDock signature.
+ *    Override: set FORGE_ALLOW_AI_ATTRIBUTION=1 in the shell environment before
+ *    starting Claude Code (operator-set only — same process.env semantics as
+ *    the gist guard above).
+ *
+ * Rules 1-4 and 6 only apply inside a ForgeDock-managed directory (a directory
  * with a `forge.yaml` or `.forgedock` marker) — see `isForgeDockManagedCwd()`
  * (issue #1591). The hook installs into the user's global
  * `~/.claude/settings.json`, so without this guard every Bash call in every
  * repo on the machine would be subject to these ForgeDock-specific rules,
  * including unrelated repos where `main` is a legitimate PR target.
  *
+ * Rule 5 is deliberately NOT gated by `isForgeDockManagedCwd()` — it runs
+ * before that check. A filesystem-root `find` is a universal footgun with no
+ * legitimate use anywhere (unlike Rules 1-4/6, which are ForgeDock-pipeline-
+ * specific), and gating it the same way would leave it silently disabled
+ * inside git worktrees, which typically carry no `forge.yaml`/`.forgedock`
+ * marker of their own — exactly where build/review sub-agents run.
+ *
  * === Fail-open contract ===
  *
  * Any uncaught error or parse failure exits 0 (allow) — this hook must
@@ -138,6 +168,84 @@ const FORBIDDEN_PR_BASES = ["main", "master"];
 /** Labels that are always valid (non-workflow labels are not constrained). */
 const WORKFLOW_LABEL_PREFIX = "workflow:";
 
+// ---------------------------------------------------------------------------
+// Rule 5 constants (issue #2034)
+// Declared here — above the top-level `await main()` call — for the same
+// reason the label-transition/PR-base constants above are: a top-level
+// `await` suspends module evaluation at that statement, so any top-level
+// `const` declared textually AFTER it (unlike hoisted `function` declarations)
+// is still in its temporal dead zone when `main()` first runs, and would
+// throw a ReferenceError the instant `checkFindRoot()` reads it — silently
+// swallowed by main()'s fail-open catch, defeating the whole rule.
+// ---------------------------------------------------------------------------
+
+/**
+ * Match a `find` search-root token that is exactly the filesystem root (`/`)
+ * or a bare Git-Bash drive mount (`/c`, `/d`, `/C`, ... — a single letter,
+ * case-insensitive, optionally followed by nothing else). Deliberately does
+ * NOT match `/c/Users/...` or any other scoped absolute path — only the bare
+ * root/drive-mount token itself.
+ */
+const FIND_ROOT_TOKEN_RE = /^\/(?:[a-zA-Z])?$/;
+
+/**
+ * Shell metacharacters that can glue a command name to an adjacent token
+ * without whitespace (e.g. `cd /tmp;find /`, `$(find /...)`, `` `find /` ``,
+ * `echo x&&find /`). `tokenizeCommand()` only splits on whitespace and
+ * quotes, so without this extra split step a `find` immediately following
+ * one of these characters stays fused into the previous token (e.g. the
+ * single token `/tmp;find` or `$(find`) and is never recognized as a `find`
+ * invocation — a real, exploitable bypass of Rule 5 (issue #2034 review
+ * finding SEC-1). Declared here (above `try { await main(); }`) for the
+ * same temporal-dead-zone reason as `FIND_ROOT_TOKEN_RE` above.
+ */
+const SHELL_METACHAR_SPLIT_RE = /[;&|()$`]+/;
+
+// ---------------------------------------------------------------------------
+// Attribution guard constants (Rule 6)
+// Declared here — above the top-level `await main()` call — so they are
+// initialized before the hook runs, for the same temporal-dead-zone reason
+// documented for the Rule 5 constants above. `checkAttribution` (a hoisted
+// function declaration) is defined further down, but the const values it
+// closes over must exist at call time or the reference throws into the
+// fail-open catch, silently defeating the rule.
+// ---------------------------------------------------------------------------
+
+/**
+ * Canonical ForgeDock signature line. The single source of truth for the
+ * pipeline's brand footer — command specs (work-on/review, review-pr,
+ * work-on/investigate) render this same wording. Kept here so the enforcement
+ * message can quote the exact replacement the agent should use.
+ */
+const FORGEDOCK_SIGNATURE =
+  "⚒️ Orchestrated with [ForgeDock](https://github.com/RapierCraftStudios/ForgeDock) — state, scheduling, review, and memory on GitHub.";
+
+/**
+ * Markers of the Claude Code harness default attribution. These are the exact
+ * signatures the assistant appends by default to commits and PR bodies; none
+ * of them belong in a repo's public commit/PR/issue history when the work is
+ * produced by the ForgeDock pipeline.
+ *
+ * Matching is case-insensitive and scoped (below) to commands that actually
+ * write a commit message or a GitHub body/comment, so mentions of "Claude
+ * Code" in unrelated commands (docs edits, greps) never trip this rule.
+ */
+const AI_ATTRIBUTION_MARKERS = [
+  /generated\s+with\s+\[?claude\s+code/i, // "🤖 Generated with [Claude Code](...)" / "Generated with Claude Code"
+  /co-authored-by:\s*claude/i,            // "Co-Authored-By: Claude ..."
+  /noreply@anthropic\.com/i,              // the anthropic co-author trailer email
+];
+
+/**
+ * Commands that carry a commit message or a GitHub body/comment — the only
+ * surfaces where an attribution footer can be persisted to history.
+ */
+const ATTRIBUTION_SCOPED_COMMANDS = [
+  /git\s+commit\b/,
+  /gh\s+pr\s+(?:create|edit|comment)\b/,
+  /gh\s+issue\s+(?:create|edit|comment)\b/,
+];
+
 // ---------------------------------------------------------------------------
 // Main — fail-open wrapper
 // ---------------------------------------------------------------------------
@@ -168,13 +276,25 @@ async function main() {
   // Only intercept Bash tool calls.
   if (toolName !== "Bash") { process.exit(0); return; }
 
-  // Only enforce inside a ForgeDock-managed project — this hook installs
-  // globally (~/.claude/settings.json), so without this guard both rules
-  // below would fire in every unrelated repo on the machine (issue #1591).
-  if (!(await isForgeDockManagedCwd())) { process.exit(0); return; }
-
   const command = String(toolInput.command || "");
 
+  // --- Rule 5: Filesystem-root `find` guard ---
+  // Deliberately checked BEFORE the isForgeDockManagedCwd() gate below — a
+  // root-anchored `find` is a universal footgun with no legitimate use in
+  // any directory (managed or not), and must fire inside git worktrees,
+  // which typically carry no forge.yaml/.forgedock marker (issue #2034).
+  const findRootViolation = checkFindRoot(command);
+  if (findRootViolation) {
+    process.stderr.write(findRootViolation);
+    process.exit(2);
+    return;
+  }
+
+  // Only enforce Rules 1-4 and 6 inside a ForgeDock-managed project — this hook
+  // installs globally (~/.claude/settings.json), so without this guard those
+  // rules would fire in every unrelated repo on the machine (issue #1591).
+  if (!(await isForgeDockManagedCwd())) { process.exit(0); return; }
+
   // --- Rule 1: PR branch target validation ---
   const prViolation = checkPrTarget(command);
   if (prViolation) {
@@ -207,6 +327,14 @@ async function main() {
     return;
   }
 
+  // --- Rule 6: Attribution guard ---
+  const attributionViolation = checkAttribution(command);
+  if (attributionViolation) {
+    process.stderr.write(attributionViolation);
+    process.exit(2);
+    return;
+  }
+
   process.exit(0);
 }
 
@@ -508,6 +636,177 @@ function checkGistVisibility(command) {
   return null;
 }
 
+// ---------------------------------------------------------------------------
+// Rule 5: Filesystem-root `find` guard (issue #2034)
+// ---------------------------------------------------------------------------
+
+/**
+ * Break each unquoted token from `tokenizeCommand()` on shell metacharacters
+ * (`;`, `&`, `|`, `(`, `)`, `$`, `` ` ``) to recover `find` as its own
+ * logical token even when it was written with no separating whitespace from
+ * a command separator or a command-substitution opener (`$(find ...)`).
+ *
+ * A token is only passed through UNSPLIT (treated as inert argument text —
+ * e.g. a `--body` value that merely *mentions* `find /` in prose) when its
+ * quoting actually spans EMBEDDED WHITESPACE, proving the quotes were used
+ * to glue multiple real words into one argument. `quoted` alone is NOT a
+ * sufficient signal: `tokenizeCommand()` sets `quoted = true` the moment ANY
+ * quote character appears anywhere in a token, including a degenerate empty
+ * pair (`""`, `''`) glued onto otherwise-unquoted text. A command like
+ * `cd /tmp;""find /` tokenizes to a single token `/tmp;find` flagged
+ * `quoted: true` even though nothing was actually protected by the empty
+ * quotes — real shells treat `""find` as the plain word `find`. Passing
+ * that token through unsplit hid `find` inside `/tmp;find`, which never
+ * exact-matches `"find"` in `checkFindRoot()`, bypassing the guard (issue
+ * #2059). This mirrors the exact discriminator `extractFlag()` already uses
+ * for the same class of decoy (issues #1519, #1591): "was quoted at all" is
+ * the wrong test; "does the token contain embedded whitespace" is right.
+ *
+ * @param {string} command
+ * @returns {string[]} Flattened list of logical token strings, in order.
+ */
+function extractLogicalTokens(command) {
+  const raw = tokenizeCommand(command);
+  const logical = [];
+  for (const { value, quoted } of raw) {
+    if (quoted && /\s/.test(value)) {
+      logical.push(value);
+      continue;
+    }
+    for (const piece of value.split(SHELL_METACHAR_SPLIT_RE)) {
+      if (piece.length > 0) logical.push(piece);
+    }
+  }
+  return logical;
+}
+
+/**
+ * Check whether a Bash command contains a `find` invocation whose search
+ * root is the filesystem root (`/`) or a bare Git-Bash drive mount (`/c`,
+ * `/d`, ...). On Windows Git Bash, `/` spans every mounted drive, so a
+ * root-anchored `find` never terminates and accumulates as an orphaned,
+ * CPU-exhausting process (issue #2034 — #1984 was a narrow precursor fix
+ * that only patched a single call site + added a prose guardrail; this is
+ * the systemic, deterministic follow-up).
+ *
+ * Scans ALL logical tokens for a `find` occurrence (not just the first word
+ * of the command), so it catches `find` appearing after `&&`, `;`, `|`, a
+ * command-substitution opener (`$(find ...)`), or backticks — not just a
+ * command that starts with `find`. Matching is case-insensitive on the
+ * command name (Windows resolves `Find`/`FIND` to the same binary as
+ * `find`) but NOT on the root-path token itself (POSIX paths are
+ * case-sensitive). Uses `extractLogicalTokens()` (quote-aware, and
+ * metacharacter-aware) so flag-shaped or path-shaped text embedded inside
+ * an unrelated quoted `--title`/`--body` value is never misread as a real
+ * `find` invocation (same class of decoy documented for `extractFlag()` —
+ * issues #1519, #1591), while a `find` glued to a shell metacharacter with
+ * no whitespace is still caught (issue #2034 review finding SEC-1/SEC-2).
+ *
+ * For each `find` token found, the search root is taken as the first
+ * following token that is not itself a `find` option (an option either
+ * starts with `-` or is `!` — `find`'s own root argument is always a bare
+ * positional path, never flag-shaped; the grouping operators `(`/`)` are
+ * shell metacharacters already stripped out by `extractLogicalTokens()`).
+ * Only an EXACT match against `FIND_ROOT_TOKEN_RE` blocks — `find
+ * /c/Users/.../repo -maxdepth 2 -name x` and `find "$REPO_PATH" ...` are
+ * legitimate, scoped searches and must be allowed.
+ *
+ * No operator override exists for this rule (unlike Rules 4/6-attribution)
+ * — a root-anchored `find` has no legitimate use in any ForgeDock pipeline.
+ *
+ * @param {string} command
+ * @returns {string|null} Error message to show, or null if allowed.
+ */
+function checkFindRoot(command) {
+  if (!command) return null;
+  // Cheap pre-filter to skip tokenization for the common case of a command
+  // with no `find` anywhere. Quote characters AND backslashes are stripped
+  // first so a degenerate/empty quote pair (`"f"ind`) or a backslash-escape
+  // (`f\ind` — real bash for the plain word `find`) glued inside the word
+  // itself doesn't break the substring match and cause a false "no find
+  // here" short-circuit that skips tokenization entirely (issue #2059,
+  // including the backslash-escape variant found in that issue's review).
+  if (!/find/i.test(command.replace(/["'\\]/g, ""))) return null;
+
+  const tokens = extractLogicalTokens(command);
+
+  for (let i = 0; i < tokens.length; i++) {
+    if (tokens[i].toLowerCase() !== "find") continue;
+
+    // The search root is the first token after `find` that isn't a `find`
+    // option. `find` options always start with `-` (e.g. -maxdepth, -iname)
+    // or are `!` — the root path is always a bare positional token.
+    let rootToken = null;
+    for (let j = i + 1; j < tokens.length; j++) {
+      const val = tokens[j];
+      if (val.startsWith("-") || val === "!") continue;
+      rootToken = val;
+      break;
+    }
+
+    if (rootToken && FIND_ROOT_TOKEN_RE.test(rootToken)) {
+      return [
+        `[ForgeDock] BLOCKED: \`find\` rooted at filesystem root "${rootToken}".`,
+        ``,
+        `A \`find\` search starting at "${rootToken}" scans every mounted drive on`,
+        `Windows and never terminates — it becomes an orphaned, CPU-exhausting`,
+        `process once the parent sub-agent exits (issue #2034).`,
+        ``,
+        `Fix: scope the search to $REPO_PATH or a known path, e.g.:`,
+        `  find "$REPO_PATH" -iname "<pattern>"`,
+        ``,
+        `No override exists for this rule — a root-anchored \`find\` has no`,
+        `legitimate use in any ForgeDock pipeline.`,
+      ].join("\n");
+    }
+  }
+
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Rule 6: Attribution guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether a commit/PR/issue command carries Claude Code default
+ * attribution. Blocks it so ForgeDock-branded pipeline output never inherits
+ * the assistant-tool signature.
+ *
+ * Override: FORGE_ALLOW_AI_ATTRIBUTION=1 in the operator's shell environment
+ * (read at hook startup, not from the tool payload — agents cannot set it via
+ * a Bash tool call in the same session).
+ *
+ * @param {string} command
+ * @returns {string|null} Error message to show, or null if allowed.
+ */
+function checkAttribution(command) {
+  // Operator override.
+  if (process.env.FORGE_ALLOW_AI_ATTRIBUTION === "1") return null;
+
+  // Only scan commands that persist a message/body to history.
+  if (!ATTRIBUTION_SCOPED_COMMANDS.some((re) => re.test(command))) return null;
+
+  const hit = AI_ATTRIBUTION_MARKERS.find((re) => re.test(command));
+  if (!hit) return null;
+
+  return [
+    `[ForgeDock] BLOCKED: Claude Code default attribution in a commit/PR/issue.`,
+    ``,
+    `The command carries the assistant-tool attribution ("🤖 Generated with`,
+    `Claude Code" / "Co-Authored-By: Claude" / noreply@anthropic.com). Pipeline`,
+    `output is ForgeDock-branded — this must never land in the repo's public`,
+    `commit, PR, or issue history.`,
+    ``,
+    `Fix: remove the attribution line/trailer. If you want a brand footer, use`,
+    `the ForgeDock signature instead:`,
+    `  ${FORGEDOCK_SIGNATURE}`,
+    ``,
+    `Exception: set FORGE_ALLOW_AI_ATTRIBUTION=1 in your shell environment BEFORE`,
+    `starting Claude Code if you intentionally need the assistant attribution.`,
+  ].join("\n");
+}
+
 // ---------------------------------------------------------------------------
 // Git helpers
 // ---------------------------------------------------------------------------
@@ -552,10 +851,14 @@ function currentGitBranch() {
  * quoted" is the wrong discriminator.
  *
  * This is intentionally NOT a full POSIX shell parser — it doesn't handle
- * escapes, `$()`, backticks, or command chaining. It only needs to be
- * accurate enough to distinguish "a flag in argument position" from
- * "flag-shaped text embedded inside a different argument's value", which is
- * all `extractFlag` needs (issue #1519).
+ * `$()`, backticks, or command chaining. It DOES handle backslash-escapes
+ * outside quotes (`\X` collapses to the literal character `X`, matching real
+ * bash semantics) — added for issue #2059 to close a `find`-guard bypass
+ * where `f\ind` tokenized with a literal backslash byte and never
+ * exact-matched `"find"`. It only needs to be accurate enough to distinguish
+ * "a flag in argument position" from "flag-shaped text embedded inside a
+ * different argument's value", which is all `extractFlag` needs (issue
+ * #1519), and to recover `find` as its own token regardless of escaping.
  *
  * @param {string} command
  * @returns {CommandToken[]}
@@ -582,6 +885,24 @@ function tokenizeCommand(command) {
       continue;
     }
 
+    // Backslash-escape (outside quotes only — matches real bash semantics for
+    // `\X` when not already inside single/double quotes). A backslash strips
+    // the special meaning of the following character and the pair collapses
+    // to that character literally: `f\ind` is the plain word `find` to a real
+    // shell. Without this, `extractLogicalTokens()`'s exact-match check
+    // against `"find"` never fires because the token still contains a literal
+    // backslash byte (issue #2059 review finding — CONFIRMED HIGH). If the
+    // escaped character is whitespace, treat the token as `quoted` (glued
+    // words), mirroring the embedded-whitespace decoy-protection discriminator
+    // used elsewhere in this file for real quoting (issues #1519, #1591).
+    if (ch === "\\" && i + 1 < command.length) {
+      const next = command[i + 1];
+      current += next;
+      if (/\s/.test(next)) quoted = true;
+      i++; // consume the escaped character; the for-loop's own increment moves past it
+      continue;
+    }
+
     if (ch === "'") {
       inSingle = true;
       quoted = true;

package/bin/init-enrich-api.mjs

@@ -1,8 +1,9 @@
 /**
  * init-enrich-api.mjs — Anthropic API enrichment backend for ForgeDock init.
  *
- * Implements the same enrich(ConfigDraft) contract as the skill backend so the
- * selection ladder in forgedock.mjs can treat both backends interchangeably.
+ * Implements the same enrich(ConfigDraft) contract as the cli backend
+ * (bin/init-enrich-cli.mjs) so the selection ladder in bin/init-enrich.mjs
+ * can treat both backends interchangeably.
  *
  * Uses Node.js built-in fetch (Node 18+) — no SDK dependency required.
  * Reads ANTHROPIC_API_KEY from the environment; cleanly skips enrichment with
@@ -153,10 +154,17 @@ export function parseEnrichedDraft(output, draft) {
  * baseline.
  *
  * @param {object} draft - ConfigDraft from detectConfig()
+ * @param {object} [opts]
+ * @param {object} [opts.env] - Environment to read ANTHROPIC_API_KEY from.
+ *   Defaults to process.env. Injectable so callers (bin/init-enrich.mjs's
+ *   dispatcher, which itself receives it from bin/journey.mjs's ctx.env) can
+ *   exercise this backend deterministically in tests without depending on
+ *   the real process environment.
  * @returns {Promise<object>} Enriched ConfigDraft, or the original draft on failure
  */
-export async function enrich(draft) {
-  const apiKey = process.env.ANTHROPIC_API_KEY;
+export async function enrich(draft, opts = {}) {
+  const { env = process.env } = opts;
+  const apiKey = env.ANTHROPIC_API_KEY;
 
   if (!apiKey) {
     console.error(