session-orchestrator 3.17.0 → 3.19.0

package/hooks/pre-bash-templates-first.mjs

@@ -22,8 +22,8 @@
  *   G7 transcript inspection via hooks/_lib/transcript-history.mjs.
  *      If any prior Read tool call matches one of the host-specific template
  *      paths from the policy, exit 0.
- *   G8 fall-through: emit deny via stdout JSON + structured stderr listing the
- *      template paths, and exit 2.
+ *   G8 fall-through: emit the PreToolUse deny envelope on stdout via emitDeny
+ *      (exit 0) with the template-path list + ack hint inside the reason.
  *
  * Fail-safe posture: any internal exception is swallowed in main().catch and
  * the hook exits 0 (allow). Rationale matches pre-bash-destructive-guard.mjs:
@@ -31,14 +31,17 @@
  * worst case is a missed enforcement, not a wedged session.
  *
  * Exit codes:
- *   0  — pass-through (G1-G3 short-circuits, bypass match, acknowledgement, Read found, error)
- *   2  — deny + structured JSON on stdout (PRD § 3 Gherkin Pattern 3)
+ *   0  — every path. Pass-through (G1-G3 short-circuits, bypass match,
+ *        acknowledgement, Read found, error) emits nothing; G8 emits the deny
+ *        envelope on stdout. Exit 2 is NEVER used: Claude Code discards stdout
+ *        on exit 2, which would throw away the deny envelope entirely (#906).
  */
 
-import { readStdin, emitAllow } from '../scripts/lib/io.mjs';
+import { readStdin, emitAllow, emitDeny } from '../scripts/lib/io.mjs';
 import { resolveProjectDir, resolvePluginRoot } from '../scripts/lib/platform.mjs';
 import { readJson } from '../scripts/lib/common.mjs';
 import { hasReadInSession } from './_lib/transcript-history.mjs';
+import { resolveHost, matchesBypass } from './_lib/vcs-create-matcher.mjs';
 
 import { shouldRunHook } from './_lib/profile-gate.mjs';
 import { existsSync, readdirSync, lstatSync } from 'node:fs';
@@ -54,13 +57,11 @@ if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
 // ---------------------------------------------------------------------------
 
 /**
- * Matches the canonical `gh` / `glab` issue/PR/MR creation invocations.
- * Anchored at start (^) with optional leading whitespace to catch indented
- * shell snippets. Word-boundary at the end avoids false positives on tokens
- * like `created` or `news`. Edit operations (`gh pr edit`, `glab mr edit`)
- * are deliberately out of scope per PRD § 2 Out-of-Scope.
+ * The `gh`/`glab` create matcher (`CREATE_REGEX`, `resolveHost`,
+ * `matchesBypass`) now lives in `hooks/_lib/vcs-create-matcher.mjs` so the
+ * sibling issue-budget hook parses create commands with byte-identical
+ * semantics instead of a diverging copy. Behaviour here is unchanged.
  */
-const CREATE_REGEX = /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/;
 
 /**
  * Default acknowledgement path, relative to project root. Used when the
@@ -68,14 +69,91 @@ const CREATE_REGEX = /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/;
  */
 const DEFAULT_ACK_PATH = '.orchestrator/runtime/templates-acknowledged.json';
 
+/**
+ * Ceiling (in characters) for the raw bash command echoed into the deny reason.
+ *
+ * ## Why this file needs its own bound at all (#919, follow-up to #906)
+ *
+ * `command` is the ONE attacker/agent-controlled term in the reason — every
+ * other line is fixed text or a repo-derived path list. Echoing it unbounded
+ * made this hook the shortest path to the failure mode #906 was repaired for:
+ * a reason large enough to push the stdout envelope past the 65 536-byte kernel
+ * pipe buffer, where a truncated envelope reads as "no decision" and the tool
+ * call is ALLOWED. `emitDeny`'s {@link DENY_REASON_MAX} clamp (16 000) now
+ * stands in that path, but a consumer that respects the bound itself is the
+ * more robust shape — defence in depth, not reliance on the single downstream
+ * clamp.
+ *
+ * The clamp alone is also NOT sufficient here, which is the concrete bug this
+ * constant fixes rather than merely hardens against. `Command:` is line 2 of 6;
+ * the template-path list and the `/templates-ack` hint are lines 3-6. A
+ * 200 000-char command therefore consumed the entire 16 000-char budget and cut
+ * the remedy off the end — the deny still bit, but PRD § 3 Gherkin Pattern 3's
+ * required content never reached the reader.
+ *
+ * ## Why 512 and not the 80 used at the two stderr sites below
+ *
+ * This file already truncates `command` twice (bypass-matched and
+ * no-templates-found), both at `slice(0, 80)`. Those are one-line **stderr log**
+ * lines, where 80 is the terminal-width convention — a different consumer class.
+ * The repo's precedent for bounding a bash command inside a **structured record
+ * field** is `hooks/pre-bash-staging-fence.mjs` (`staged_paths[].command`,
+ * `slice(0, 512)`), and `permissionDecisionReason` is exactly that: a structured
+ * field, not a log line. Reusing 512 follows the matching house convention
+ * instead of inventing a third number. Reusing 80 would clip a realistic
+ * `gh pr create --title … --body …` mid-flag, defeating the recognisability the
+ * line exists to provide.
+ *
+ * Bound check: the fixed part of this reason measures 348 chars (see the
+ * call-site table in `scripts/lib/io.mjs`), so the worst case is 348 + 512 +
+ * the path list — ~19× below `DENY_REASON_MAX` and ~76× below the pipe buffer.
+ * This hook no longer contributes an unbounded term to the envelope at all.
+ */
+const COMMAND_ECHO_MAX = 512;
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
 
 /**
- * Block the create command: write structured deny JSON to stdout + exit 2.
- * Mirrors the exact format from pre-bash-destructive-guard.mjs blockCommand()
- * so downstream Claude Code rendering is consistent.
+ * Clip the echoed command to {@link COMMAND_ECHO_MAX}, marking the cut so the
+ * reader can tell the command was truncated rather than ending there.
+ *
+ * The marker is budgeted INSIDE the ceiling — mirroring `_clampReason` in
+ * `scripts/lib/io.mjs` — so the returned string never exceeds it and the
+ * worst-case reason length stays a fixed, auditable number.
+ *
+ * @param {string} command
+ * @returns {string}
+ */
+function clipCommand(command) {
+  if (command.length <= COMMAND_ECHO_MAX) return command;
+  const marker = `… [truncated: showing ${COMMAND_ECHO_MAX} of ${command.length} characters]`;
+  return command.slice(0, COMMAND_ECHO_MAX - marker.length) + marker;
+}
+
+/**
+ * Block the create command: emit the PreToolUse deny envelope via emitDeny
+ * (exit 0). Mirrors pre-bash-destructive-guard.mjs blockCommand() so downstream
+ * Claude Code rendering is consistent.
+ *
+ * PRD § 3 Gherkin Pattern 3 requires the template-path list plus the
+ * `/templates-ack` hint to reach the reader. That requirement is UNCHANGED —
+ * only the channel moved (#906). Until #906 this text was written to stderr AND
+ * duplicated into an `exit 2` stdout envelope, the mixed form the hook docs
+ * forbid ("choose one approach per hook, not both"). Under exit 0, stderr is
+ * only surfaced in the debug log — invisible to both operator and model — so a
+ * stderr write would look alive while being dead. The full multi-line text
+ * therefore travels as the emitDeny `reason`, landing in
+ * `permissionDecisionReason`, which is fed to **Claude** — the actor that has
+ * to read the template or run `/templates-ack`. The operator sees the first
+ * line via the derived `systemMessage` headline.
+ *
+ * The echoed `command` is bounded by {@link COMMAND_ECHO_MAX} before it enters
+ * the reason: it is the only agent-controlled term here, and left unbounded it
+ * both risked the pipe-buffer fail-open #906 repaired AND pushed the template
+ * list plus the ack hint past `emitDeny`'s clamp — i.e. truncated away exactly
+ * the content the PRD requires. See that constant for the full rationale.
  *
  * @param {{ host: string, command: string, templatePaths: string[],
  *           ackFile: string }} ctx
@@ -88,21 +166,16 @@ function blockCreate(ctx) {
     : '  (none configured)';
   const reason = [
     `pre-bash-templates-first: ${host} create call detected without prior template Read.`,
-    `Command: ${command}`,
+    `Command: ${clipCommand(command)}`,
     `Found templates:`,
     pathList,
     `Read one of these first, OR run \`/templates-ack\` (writes ${ackFile}) to bypass for this session.`,
     `See: issue #519, "gsd Pattern Adoption Quick-Wins" (archived in the private Meta-Vault) (Pattern 3)`,
   ].join('\n');
 
-  // PRD § 3 Gherkin Pattern 3 spec: stderr lists template paths + ack hint.
-  // We emit BOTH stderr (human-readable per spec) AND the structured stdout
-  // JSON envelope (machine-readable for Claude Code hook protocol).
-  process.stderr.write(reason + '\n');
-  process.stdout.write(
-    JSON.stringify({ permissionDecision: 'deny', reason }) + '\n',
-  );
-  process.exit(2);
+  // Single channel: the full multi-line reason (template paths + ack hint)
+  // rides in permissionDecisionReason. Never returns.
+  emitDeny(reason);
 }
 
 /**
@@ -142,46 +215,6 @@ function resolvePolicyPath(projectDir) {
   return null;
 }
 
-/**
- * Determine which host the command targets by inspecting the CREATE_REGEX
- * capture. `gh` → "github", `glab` → "gitlab".
- *
- * @param {string} command
- * @returns {"github"|"gitlab"|null}
- */
-function resolveHost(command) {
-  const m = command.match(CREATE_REGEX);
-  if (!m) return null;
-  return m[1] === 'gh' ? 'github' : 'gitlab';
-}
-
-/**
- * True when the command starts with any of the bypass patterns. Bypass match
- * is a prefix check with a word/EOL boundary on the trailing edge — this
- * prevents trivial bypass via prefix-inclusion (e.g. policy entry
- * "gh issue create --label bot" must not match "gh issue create --label botanical").
- *
- * @param {string} command
- * @param {string[]} bypassPatterns
- * @returns {boolean}
- */
-function matchesBypass(command, bypassPatterns) {
-  if (!Array.isArray(bypassPatterns) || bypassPatterns.length === 0) {
-    return false;
-  }
-  const stripped = command.replace(/^\s+/, '');
-  for (const pat of bypassPatterns) {
-    if (typeof pat !== 'string' || pat.length === 0) continue;
-    const patStripped = pat.replace(/^\s+/, '');
-    if (!stripped.startsWith(patStripped)) continue;
-    // Boundary check: next character must be whitespace, EOL, or absent.
-    // This prevents "gh foo --label bot" from matching policy "gh foo --label botanical".
-    const nextChar = stripped.charAt(patStripped.length);
-    if (nextChar === '' || /\s/.test(nextChar)) return true;
-  }
-  return false;
-}
-
 /**
  * Check the acknowledgement file for the current session_id. Best-effort:
  * any read or parse error means "no acknowledgement" (returns false) so the