session-orchestrator 3.16.0

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

@@ -0,0 +1,404 @@
+#!/usr/bin/env node
+/**
+ * pre-bash-templates-first.mjs — PreToolUse hook: blocks `gh|glab pr|mr|issue
+ * create|new` invocations when no matching template was Read earlier in the
+ * session.
+ *
+ * Implements Pattern 3 of "gsd Pattern Adoption Quick-Wins" (#519; archived in
+ * the private Meta-Vault). Companion to pre-bash-destructive-guard.mjs (issue
+ * #155); both share the PreToolUse Bash matcher and run sequentially.
+ *
+ * Decision flow:
+ *   G1 tool filter — only Bash is gated; other tools pass through.
+ *   G2 command is a non-empty string.
+ *   G3 regex match against /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/.
+ *      No match → exit 0 (the call is not a create/new operation).
+ *   G4 policy load: .orchestrator/policy/templates-policy.json.
+ *      Missing → exit 0 + stderr warning. Malformed → exit 0 + stderr warning.
+ *   G5 bypass-pattern check: any entry in policy.bypass_patterns that the
+ *      command starts with → exit 0.
+ *   G6 acknowledgement-file check: if the file under the resolved acknowledgement
+ *      path contains an entry for the current session_id, exit 0.
+ *   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.
+ *
+ * Fail-safe posture: any internal exception is swallowed in main().catch and
+ * the hook exits 0 (allow). Rationale matches pre-bash-destructive-guard.mjs:
+ * a templates-first hook that crashes should not block legitimate work; the
+ * 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)
+ */
+
+import { readStdin, emitAllow } 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 { shouldRunHook } from './_lib/profile-gate.mjs';
+import { existsSync, readdirSync, lstatSync } from 'node:fs';
+import path from 'node:path';
+
+// #519: opt-in via profile/env. Default profile "full" enables this hook;
+// minimal/off disable. SO_DISABLED_HOOKS=pre-bash-templates-first opts out
+// per session.
+if (!shouldRunHook('pre-bash-templates-first')) process.exit(0);
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * 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.
+ */
+const CREATE_REGEX = /^\s*(gh|glab)\s+(pr|mr|issue)\s+(create|new)\b/;
+
+/**
+ * Default acknowledgement path, relative to project root. Used when the
+ * policy omits the `acknowledgement_file` key.
+ */
+const DEFAULT_ACK_PATH = '.orchestrator/runtime/templates-acknowledged.json';
+
+// ---------------------------------------------------------------------------
+// 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.
+ *
+ * @param {{ host: string, command: string, templatePaths: string[],
+ *           ackFile: string }} ctx
+ * @returns {never}
+ */
+function blockCreate(ctx) {
+  const { host, command, templatePaths, ackFile } = ctx;
+  const pathList = templatePaths.length > 0
+    ? templatePaths.map((p) => `  - ${p}`).join('\n')
+    : '  (none configured)';
+  const reason = [
+    `pre-bash-templates-first: ${host} create call detected without prior template Read.`,
+    `Command: ${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);
+}
+
+/**
+ * Resolve the policy file path, searching in priority order. Mirrors the
+ * resolution chain in pre-bash-destructive-guard.mjs so administrators only
+ * have to maintain a single mental model for policy locations.
+ *
+ * @param {string|null} projectDir
+ * @returns {string|null}
+ */
+function resolvePolicyPath(projectDir) {
+  const candidates = [
+    path.join(
+      process.cwd(),
+      '.orchestrator',
+      'policy',
+      'templates-policy.json',
+    ),
+  ];
+
+  if (projectDir && projectDir !== process.cwd()) {
+    candidates.push(
+      path.join(projectDir, '.orchestrator', 'policy', 'templates-policy.json'),
+    );
+  }
+
+  const pluginRoot = resolvePluginRoot();
+  if (pluginRoot) {
+    candidates.push(
+      path.join(pluginRoot, '.orchestrator', 'policy', 'templates-policy.json'),
+    );
+  }
+
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  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
+ * subsequent transcript-history check still runs. The acknowledgement file
+ * schema is intentionally minimal:
+ *
+ *   { "<session_id>": { "acknowledgedAt": "<ISO timestamp>" } }
+ *
+ * A future /templates-ack command writes this file; the hook only reads it.
+ *
+ * @param {string} ackFilePath
+ * @param {string|null} sessionId
+ * @returns {Promise<boolean>}
+ */
+async function isAcknowledged(ackFilePath, sessionId) {
+  if (!sessionId || typeof sessionId !== 'string') return false;
+  if (!existsSync(ackFilePath)) return false;
+  try {
+    const data = await readJson(ackFilePath);
+    if (!data || typeof data !== 'object') return false;
+    const entry = data[sessionId];
+    return Boolean(entry && typeof entry === 'object' && entry.acknowledgedAt);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Pull the session_id from the hook stdin payload, with a single fallback
+ * to the persisted file written by on-session-start.mjs. Returns null when
+ * neither source yields a string.
+ *
+ * @param {object|null} input
+ * @param {string|null} projectDir
+ * @returns {Promise<string|null>}
+ */
+async function resolveSessionId(input, projectDir) {
+  const fromStdin = input?.session_id ?? input?.sessionId ?? null;
+  if (typeof fromStdin === 'string' && fromStdin.length > 0) return fromStdin;
+
+  if (!projectDir) return null;
+  const persisted = path.join(projectDir, '.orchestrator', 'current-session.json');
+  if (!existsSync(persisted)) return null;
+  try {
+    const data = await readJson(persisted);
+    if (data && typeof data === 'object') {
+      const sid = data.session_id ?? data.sessionId ?? null;
+      if (typeof sid === 'string' && sid.length > 0) return sid;
+    }
+  } catch {
+    // ignore — null below
+  }
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const input = await readStdin();
+  if (!input) return emitAllow();
+
+  // G1 — only Bash is gated.
+  if (input.tool_name !== 'Bash') return emitAllow();
+
+  // G2 — command must be a non-empty string.
+  const command = input?.tool_input?.command;
+  if (typeof command !== 'string' || command.length === 0) return emitAllow();
+
+  // G3 — regex gate. Non-matching commands pass through unconditionally.
+  const host = resolveHost(command);
+  if (!host) return emitAllow();
+
+  const projectDir = resolveProjectDir();
+
+  // G4 — policy load.
+  const policyPath = resolvePolicyPath(projectDir);
+  if (!policyPath) {
+    process.stderr.write(
+      '⚠ pre-bash-templates-first: policy file not found ' +
+        '(.orchestrator/policy/templates-policy.json) — skipping guard\n',
+    );
+    return emitAllow();
+  }
+
+  let policy;
+  try {
+    policy = await readJson(policyPath);
+  } catch {
+    process.stderr.write(
+      '⚠ pre-bash-templates-first: policy file is malformed (invalid JSON) — skipping guard\n',
+    );
+    return emitAllow();
+  }
+
+  if (!policy || typeof policy !== 'object') {
+    process.stderr.write(
+      '⚠ pre-bash-templates-first: policy file empty or non-object — skipping guard\n',
+    );
+    return emitAllow();
+  }
+
+  // Enforcement off → allow without inspection.
+  if (policy.enforcement === 'off') return emitAllow();
+
+  // G5 — bypass-pattern check.
+  if (matchesBypass(command, policy.bypass_patterns)) {
+    process.stderr.write(
+      `ℹ pre-bash-templates-first: bypass-pattern matched, allowing '${command.slice(0, 80)}'\n`,
+    );
+    return emitAllow();
+  }
+
+  // Resolve the acknowledgement file path (policy override or default).
+  const ackRel =
+    typeof policy.acknowledgement_file === 'string' && policy.acknowledgement_file.length > 0
+      ? policy.acknowledgement_file
+      : DEFAULT_ACK_PATH;
+  const ackFile = path.isAbsolute(ackRel)
+    ? ackRel
+    : path.join(projectDir || process.cwd(), ackRel);
+
+  // G6 — acknowledgement-file check.
+  const sessionId = await resolveSessionId(input, projectDir);
+  if (await isAcknowledged(ackFile, sessionId)) {
+    return emitAllow();
+  }
+
+  // G7 — transcript inspection.
+  // The hook stdin payload carries `transcript_path` per Claude Code's hook
+  // contract. When absent (older harness, Codex/Cursor port, manual smoke
+  // test) we treat it as "no evidence of prior Read" and fall through to
+  // deny — that is the default-deny safety posture for this gate.
+  const hostBlock = policy.hosts?.[host] ?? {};
+  const templatePathsConfigured = Array.isArray(hostBlock.template_paths)
+    ? hostBlock.template_paths.filter((p) => typeof p === 'string' && p.length > 0)
+    : [];
+
+  // Resolve configured paths to ACTUAL files on disk in the project.
+  // - File pattern (e.g. .github/PULL_REQUEST_TEMPLATE.md) → include if exists.
+  // - Directory pattern (e.g. .gitlab/merge_request_templates/) → expand to
+  //   all *.md files inside (and inside immediate subdirs for ISSUE_TEMPLATE/).
+  // If NO templates resolve, nothing to enforce → allow.
+  const projectBase = projectDir || process.cwd();
+  const templatePaths = [];
+  for (const p of templatePathsConfigured) {
+    const abs = path.isAbsolute(p) ? p : path.join(projectBase, p);
+    if (!existsSync(abs)) continue;
+    let stat;
+    try {
+      const lstat = lstatSync(abs);
+      if (lstat.isSymbolicLink()) {
+        process.stderr.write(`⚠ pre-bash-templates-first: template path is a symlink (${p}) — rejected for security\n`);
+        continue;
+      }
+      stat = lstat;
+    } catch { continue; }
+    if (stat.isFile()) {
+      templatePaths.push(p);
+      continue;
+    }
+    if (stat.isDirectory()) {
+      let entries;
+      try { entries = readdirSync(abs); } catch { continue; }
+      const trimmed = p.endsWith('/') ? p.slice(0, -1) : p;
+      for (const entry of entries) {
+        if (entry.startsWith('.')) continue;
+        const entryAbs = path.join(abs, entry);
+        let estat;
+        try {
+          const elstat = lstatSync(entryAbs);
+          if (elstat.isSymbolicLink()) {
+            // Silent skip: symlinks inside template directories are not enforced templates.
+            continue;
+          }
+          estat = elstat;
+        } catch { continue; }
+        if (estat.isFile() && (entry.endsWith('.md') || entry.endsWith('.yml') || entry.endsWith('.yaml'))) {
+          templatePaths.push(`${trimmed}/${entry}`);
+        }
+      }
+    }
+  }
+
+  if (templatePaths.length === 0) {
+    process.stderr.write(
+      `ℹ pre-bash-templates-first: no ${host} template files found in repo — allowing '${command.slice(0, 80)}'\n`,
+    );
+    return emitAllow();
+  }
+
+  const transcriptPath =
+    typeof input.transcript_path === 'string' && input.transcript_path.length > 0
+      ? input.transcript_path
+      : null;
+
+  if (transcriptPath && templatePaths.length > 0) {
+    const result = await hasReadInSession(templatePaths, transcriptPath);
+    if (result.matched) return emitAllow();
+  }
+
+  // G8 — deny.
+  blockCreate({
+    host,
+    command,
+    templatePaths,
+    ackFile,
+  });
+}
+
+// Top-level error handler — never let exit 1 leak. Same posture as
+// pre-bash-destructive-guard.mjs: fail-open on internal errors to avoid
+// blocking legitimate work.
+main().catch((e) => {
+  process.stderr.write(
+    `⚠ pre-bash-templates-first: internal error — ${e?.message || e}\n`,
+  );
+  process.exit(0);
+});

package/hooks/run-node.sh

@@ -0,0 +1,72 @@
+#!/bin/sh
+# hooks/run-node.sh — resolve the Node.js binary robustly, then exec a plugin hook.
+#
+# Why this exists (GH Kanevry/session-orchestrator#53): the Claude Code harness
+# executes hook commands via `/bin/sh -c` with the PATH of the harness process
+# itself. That shell does NOT source ~/.zshrc / ~/.bashrc, so Node installed via
+# Homebrew on Apple Silicon (/opt/homebrew/bin), nvm, volta, or asdf may be
+# invisible to hooks even though `node` works fine in a normal terminal. A bare
+# `node ...` command then fails with "node: command not found" on EVERY hook of
+# EVERY tool call — loud, repetitive, and useless to the operator.
+#
+# Contract:
+#   sh run-node.sh <hook-script.mjs> [args...]
+#   - Resolution order: $SO_NODE_BIN override > PATH > well-known install dirs
+#     ($SO_NODE_SEARCH_DIRS, colon-separated, overrides the built-in list) > nvm.
+#   - Found:   exec's node — stdin/stdout/stderr and exit code pass through
+#              unchanged (PreToolUse exit-2 blocking still works).
+#   - Missing: prints ONE warning per rate-limit window (marker file in
+#              ${TMPDIR:-/tmp}, 6h TTL) and exits 0 so hooks degrade gracefully
+#              instead of spamming a shell error on every tool call.
+
+# 1. Explicit operator override wins.
+if [ -n "$SO_NODE_BIN" ] && [ -x "$SO_NODE_BIN" ]; then
+  exec "$SO_NODE_BIN" "$@"
+fi
+
+# 2. PATH as inherited from the harness.
+if command -v node >/dev/null 2>&1; then
+  exec node "$@"
+fi
+
+# 3. Well-known install locations (Homebrew arm64/intel, system, volta, asdf).
+search_dirs="${SO_NODE_SEARCH_DIRS:-/opt/homebrew/bin:/usr/local/bin:/usr/bin:${VOLTA_HOME:-$HOME/.volta}/bin:$HOME/.asdf/shims:$HOME/.local/bin}"
+old_ifs="$IFS"
+IFS=:
+for dir in $search_dirs; do
+  if [ -n "$dir" ] && [ -x "$dir/node" ]; then
+    IFS="$old_ifs"
+    exec "$dir/node" "$@"
+  fi
+done
+IFS="$old_ifs"
+
+# 4. nvm keeps versioned dirs; any installed version is good enough for hooks.
+#    (Glob order is lexical, not semver — acceptable for a last-resort fallback.)
+for cand in "${NVM_DIR:-$HOME/.nvm}"/versions/node/*/bin/node; do
+  if [ -x "$cand" ]; then
+    exec "$cand" "$@"
+  fi
+done
+
+# 5. Not found anywhere: degrade gracefully. Warn at most once per 6 hours so
+#    the operator gets ONE actionable diagnostic instead of per-tool-call spam.
+#    Deliberately dependency-free: a PATH broken enough to lose `node` may also
+#    lack `touch`/`find`/`id`, so the marker is written via shell redirection
+#    and `find` only upgrades the check to a 6h TTL when it happens to exist.
+marker="${TMPDIR:-/tmp}/session-orchestrator-node-missing-${USER:-uid}"
+if [ -f "$marker" ]; then
+  expired="$(find "$marker" -mmin +360 2>/dev/null || true)"
+else
+  expired="yes"
+fi
+if [ -n "$expired" ]; then
+  : > "$marker" 2>/dev/null || true
+  {
+    echo "session-orchestrator: 'node' not found on the hook PATH — plugin hooks are skipped."
+    echo "  Fix: install Node.js 24+, expose it on the harness PATH, or set SO_NODE_BIN=/abs/path/to/node."
+    echo "  (Hook shells do not source ~/.zshrc — Homebrew/nvm/volta installs can be invisible here."
+    echo "   Rate-limited to once per 6h. See README.md § Troubleshooting.)"
+  } >&2
+fi
+exit 0

package/hooks/skill-invocation-telemetry.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * skill-invocation-telemetry.mjs — PreToolUse hook for Skill tool selection.
+ *
+ * Hook event: PreToolUse with matcher:"Skill" (issue #645, epic #643).
+ * Fires when the Skill tool is invoked (a skill is selected). Writes a
+ * selection record to `.orchestrator/metrics/skill-invocations.jsonl`.
+ *
+ * Decision flow:
+ *   1. shouldRunHook gate — exit 0 immediately when the hook is disabled.
+ *   2. Read JSON payload from stdin: { tool_name, tool_input: { skill }, session_id }.
+ *   3. Belt-and-suspenders guard: if tool_name !== "Skill", exit 0 immediately.
+ *   4. Build a 'selected' record and call appendSkillInvocation().
+ *   5. Output: nothing on stdout. Diagnostic errors to stderr only.
+ *
+ * Exit codes: 0 always (informational, never blocking).
+ */
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+if (!shouldRunHook('skill-invocation-telemetry')) process.exit(0);
+
+import path from 'node:path';
+import { appendSkillInvocation } from '../scripts/lib/skill-invocations-schema.mjs';
+import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const JSONL_PATH = path.join(SO_PROJECT_DIR, '.orchestrator', 'metrics', 'skill-invocations.jsonl');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Read stdin to EOF (best-effort). Returns parsed JSON or null on failure.
+ * Uses a 5 s timeout consistent with Claude Code hook contract.
+ *
+ * @returns {Promise<object|null>}
+ */
+function readStdinJson() {
+  return new Promise((resolve) => {
+    if (process.stdin.readableEnded || process.stdin.closed) {
+      resolve(null);
+      return;
+    }
+    const chunks = [];
+    const timer = setTimeout(() => { resolve(null); }, 5_000);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => chunks.push(c));
+    process.stdin.on('end', () => {
+      clearTimeout(timer);
+      const raw = chunks.join('').trim();
+      if (!raw) { resolve(null); return; }
+      try { resolve(JSON.parse(raw)); } catch { resolve(null); }
+    });
+    process.stdin.on('error', () => { clearTimeout(timer); resolve(null); });
+    process.stdin.resume();
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const input = await readStdinJson();
+  if (!input) return;
+
+  // Belt-and-suspenders: the hooks.json matcher:"Skill" should already filter,
+  // but we guard defensively in case of misconfiguration or future matcher changes.
+  if (input.tool_name !== 'Skill') return;
+
+  const skillName = (typeof input.tool_input?.skill === 'string' && input.tool_input.skill.trim())
+    ? input.tool_input.skill.trim()
+    : 'unknown';
+
+  const sessionId = (typeof input.session_id === 'string' && input.session_id.trim())
+    ? input.session_id.trim()
+    : null;
+
+  /** @type {object} */
+  const record = {
+    timestamp: new Date().toISOString(),
+    event: 'selected',
+    skill: skillName,
+    session_id: sessionId,
+    schema_version: 1,
+  };
+
+  await appendSkillInvocation(JSONL_PATH, record);
+}
+
+// Exit 0 always — informational hook must never block the Skill tool.
+main().catch((err) => {
+  process.stderr.write(`[skill-invocation-telemetry] ERROR: ${err?.message ?? err}\n`);
+}).finally(() => process.exit(0));