session-orchestrator 3.16.0

package/hooks/cwd-change-restore.mjs

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+/**
+ * cwd-change-restore.mjs — CwdChanged hook handler.
+ *
+ * Hook event: CwdChanged (issue #342).
+ * Fires when the coordinator's working directory changes unexpectedly.
+ * Records the event in `.orchestrator/current-session.json` under the
+ * `cwd_changes` array so the coordinator and downstream skills can
+ * inspect recent directory changes without re-reading the full event log.
+ *
+ * Note: the actual CWD restoration is a harness-level concern; this
+ * handler is informational only. It mirrors the pattern used by
+ * post-tool-failure-corrective-context.mjs.
+ *
+ * Decision flow:
+ *   1. shouldRunHook gate — exit 0 immediately when the hook is disabled.
+ *   2. Read JSON payload from stdin: { previous_cwd, new_cwd }.
+ *   3. Build a compact record: { timestamp, previous_cwd, new_cwd }.
+ *   4. Atomic read-modify-write of .orchestrator/current-session.json:
+ *      append to `cwd_changes` array (create if absent), keep last 20
+ *      entries to bound file growth.
+ *   5. Output: nothing on stdout. Diagnostic errors to stderr only.
+ *
+ * Exit codes: 0 always (informational, never blocking).
+ */
+
+import { readFile, writeFile, rename, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+// Exit 0 immediately when disabled via SO_HOOK_PROFILE / SO_DISABLED_HOOKS.
+if (!shouldRunHook('cwd-change-restore')) process.exit(0);
+
+import { SO_PROJECT_DIR } from '../scripts/lib/platform.mjs';
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/** Maximum number of cwd_change entries retained per session. */
+const MAX_ENTRIES = 20;
+
+// ---------------------------------------------------------------------------
+// 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();
+  });
+}
+
+/**
+ * Atomic read-modify-write of a JSON file via temp + rename.
+ * Reads the existing file (or starts with `defaultValue` when absent),
+ * applies `mutate`, writes to a tmp file, then renames over the original.
+ * Atomic on POSIX (same-filesystem rename). Best-effort on Windows.
+ *
+ * @param {string} filePath
+ * @param {object} defaultValue — used when the file does not exist or is unparseable
+ * @param {function(object): object} mutate — synchronous pure transformer
+ */
+async function atomicMutateJson(filePath, defaultValue, mutate) {
+  let current = defaultValue;
+  try {
+    const raw = await readFile(filePath, 'utf8');
+    current = JSON.parse(raw);
+  } catch {
+    // File absent or unparseable — start from defaultValue.
+  }
+
+  const updated = mutate(current);
+  const tmp = `${filePath}.tmp-cwd-${process.pid}-${Date.now()}`;
+  await mkdir(path.dirname(filePath), { recursive: true });
+  await writeFile(tmp, JSON.stringify(updated, null, 2) + '\n', 'utf8');
+  await rename(tmp, filePath);
+}
+
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+
+async function main() {
+  const input = await readStdinJson();
+
+  const previousCwd =
+    typeof input?.previous_cwd === 'string' ? input.previous_cwd : null;
+  const newCwd =
+    typeof input?.new_cwd === 'string' ? input.new_cwd : null;
+
+  const record = {
+    timestamp: new Date().toISOString(),
+    previous_cwd: previousCwd,
+    new_cwd: newCwd,
+  };
+
+  const sessionFile = path.join(SO_PROJECT_DIR, '.orchestrator', 'current-session.json');
+
+  await atomicMutateJson(sessionFile, {}, (current) => {
+    const existing = Array.isArray(current.cwd_changes)
+      ? current.cwd_changes
+      : [];
+    // Append the new record and cap at MAX_ENTRIES (keep most-recent).
+    const updated = [...existing, record].slice(-MAX_ENTRIES);
+    return { ...current, cwd_changes: updated };
+  });
+}
+
+// Exit 0 always — informational hook must never block Claude.
+main().catch(() => {}).finally(() => process.exit(0));

package/hooks/enforce-commands.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * enforce-commands.mjs — PreToolUse hook: blocks dangerous Bash commands.
+ *
+ * Node.js port of hooks/enforce-commands.sh. Part of v3.0.0 migration
+ * (Epic #124, issue #138). ESM, Node 20+, no external dependencies beyond stdlib.
+ *
+ * Decision flow (8 gates, early-exit):
+ *   G1 tool filter — only Bash tool is gated
+ *   G2 command present + string
+ *   G3 wave-scope.json exists
+ *   G4 command-guard gate enabled
+ *   G5 enforcement != "off"
+ *   G6 blocked pattern match against .blockedCommands[], or
+ *      fallback safety list when .blockedCommands is empty
+ *   G7 strict → deny (exit 2); warn → stderr + allow (exit 0); otherwise allow
+ *
+ * SECURITY-REQ-01: try/catch on main(). emitDeny on any unhandled error —
+ *   exit 2, never exit 1. Null-guard readStdin() return.
+ * SECURITY-REQ-07: FALLBACK_BLOCKED includes 'git push -f' and 'drop table'
+ *   (short form + case variant gaps in the original Bash fallback list).
+ * SECURITY-REQ-08: scope file read exactly once per invocation.
+ */
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
+if (!shouldRunHook('enforce-commands')) process.exit(0);
+
+import path from 'node:path';
+
+import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
+import { resolveProjectDir } from '../scripts/lib/platform.mjs';
+import {
+  findScopeFile,
+  commandMatchesBlocked,
+  suggestForCommandBlock,
+  extractBashWriteTargets,
+  pathMatchesPattern,
+} from '../scripts/lib/hardening.mjs';
+import { readJson } from '../scripts/lib/common.mjs';
+
+// Fallback safety list — applied when scope.blockedCommands is empty.
+// Keep in sync with hooks/enforce-commands.sh; v3 additions (#138, SECURITY-REQ-07)
+// cover the short-form git push and the lowercase SQL variant the Bash version missed.
+const FALLBACK_BLOCKED = [
+  'rm -rf',
+  'git push --force',
+  'git push -f',
+  'git reset --hard',
+  'DROP TABLE',
+  'drop table',
+  'git checkout -- .',
+];
+
+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();
+
+  const projectRoot = resolveProjectDir();
+
+  // G3 — no scope file → allow
+  const scopePath = findScopeFile(projectRoot);
+  if (!scopePath) return emitAllow();
+
+  // SECURITY-REQ-08: read scope file exactly once; use the parsed object
+  // for all subsequent gate checks.
+  let scope;
+  try {
+    scope = await readJson(scopePath);
+  } catch {
+    scope = {};
+  }
+  const enforcement = scope.enforcement || 'strict';
+  const blockedCommands = Array.isArray(scope.blockedCommands)
+    ? scope.blockedCommands
+    : [];
+  const gateOn = scope?.gates?.['command-guard'] !== false;
+
+  // bash-write-guard (#800) — OPT-IN, WARN-ONLY, default OFF.
+  //
+  // INVERTED DEFAULT (deliberate divergence from the command-guard convention
+  // above, where a MISSING gates entry means ENABLED): this gate runs ONLY when
+  // `gates['bash-write-guard'] === true` is EXPLICITLY set. Conservative shell-
+  // write parsing carries a real false-positive risk (quoting, `>$VAR`, process
+  // substitution, pipes), so it stays off unless a wave opts in. It never denies
+  // and never changes the exit path — it only writes advisory stderr lines — so
+  // it is safe to run before the command-guard gate/enforcement early-returns.
+  // Skipped under enforcement:off (nothing is enforced there). See #800.
+  if (enforcement !== 'off' && scope?.gates?.['bash-write-guard'] === true) {
+    runBashWriteGuard(command, scope, projectRoot);
+  }
+
+  // G4 — gate disabled → allow
+  if (!gateOn) return emitAllow();
+  // G5 — enforcement "off" → allow
+  if (enforcement === 'off') return emitAllow();
+
+  // G6 — determine which list to check
+  const useFallback = blockedCommands.length === 0;
+  const patternsToCheck = useFallback ? FALLBACK_BLOCKED : blockedCommands;
+
+  for (const pattern of patternsToCheck) {
+    if (commandMatchesBlocked(command, pattern)) {
+      const prefix = useFallback
+        ? 'Blocked by fallback safety list'
+        : 'Blocked command';
+      const reason = `${prefix}: '${pattern}' found in command`;
+      const suggestion = suggestForCommandBlock(pattern);
+      if (enforcement === 'strict') {
+        return emitDeny(reason, suggestion);
+      }
+      return emitWarn(`${reason} — ${suggestion}`);
+    }
+  }
+
+  // G7 — no match → allow
+  return emitAllow();
+}
+
+/**
+ * bash-write-guard (#800) — advisory, side-effecting stderr warner.
+ *
+ * Extracts likely Bash write targets from `command`, relativises each against the
+ * project root where possible, and WARNS (stderr only) for every target that is
+ * NOT covered by the wave's allowedPaths. NEVER denies, NEVER changes the exit
+ * code — v1 is warn-only by design (#800). No event infra is pulled in: this hook
+ * has no emitEvent import, so warnings are plain stderr lines per the #800 contract.
+ *
+ * @param {string} command — raw Bash command string
+ * @param {object} scope — parsed wave-scope.json
+ * @param {string} projectRoot — absolute project root
+ */
+function runBashWriteGuard(command, scope, projectRoot) {
+  const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+  const targets = extractBashWriteTargets(command);
+  for (const target of targets) {
+    if (!targetInWaveScope(target, allowedPaths, projectRoot)) {
+      process.stderr.write(`bash-write-guard: ${target} outside wave scope (warn-only, #800)\n`);
+    }
+  }
+}
+
+/**
+ * Is a write target covered by the wave's allowedPaths? Reuses the same
+ * `pathMatchesPattern` matcher the enforce-scope path gate uses (no bespoke
+ * matching). Absolute targets inside the project root are relativised first;
+ * both the relative and raw forms are tried so an in-scope target never warns.
+ *
+ * @param {string} target — verbatim write target from extractBashWriteTargets
+ * @param {string[]} allowedPaths — wave allowedPaths union
+ * @param {string} projectRoot — absolute project root
+ * @returns {boolean}
+ */
+function targetInWaveScope(target, allowedPaths, projectRoot) {
+  if (!Array.isArray(allowedPaths) || allowedPaths.length === 0) return false;
+  let rel = target;
+  if (path.isAbsolute(target)) {
+    const fromRoot = path.relative(projectRoot, target);
+    if (fromRoot && !fromRoot.startsWith('..') && !path.isAbsolute(fromRoot)) {
+      rel = fromRoot;
+    }
+  }
+  const norm = rel.split(path.sep).join('/').replace(/^\.\//, '');
+  return allowedPaths.some(
+    (p) => pathMatchesPattern(norm, p) || pathMatchesPattern(target, p),
+  );
+}
+
+// SECURITY-REQ-01 (F-03): top-level try/catch — never let exit 1 leak.
+main().catch((e) => {
+  emitDeny('Internal hook error — request blocked for safety', `${e?.message || e}`);
+});

package/hooks/enforce-scope.mjs

@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+/**
+ * enforce-scope.mjs — PreToolUse hook: block Edit/Write/MultiEdit outside allowed wave paths.
+ *
+ * Replaces enforce-scope.sh (87-line Bash). Part of v3.0.0 Windows-native migration.
+ * Issue: github.com/Kanevry/session-orchestrator/issues/137
+ *
+ * Decision flow (8 gates + one pre-gate, early-exit):
+ *   G1  tool filter — only Edit/Write/MultiEdit are gated
+ *   G2  file_path present + string
+ *   G3  wave-scope.json exists
+ *   G4  path-guard gate enabled
+ *   G5  enforcement != "off"
+ *   G5b (#792) allowlist-first: an EXPLICIT absolute allowedPaths entry that
+ *       matches the fully realpath-resolved candidate → allow, BEFORE G6.
+ *       Runs before G6 so a deliberate out-of-repo grant (e.g. a vault path)
+ *       is reachable at all — G6 would otherwise deny every out-of-repo path
+ *       without ever consulting allowedPaths. See matchesAbsoluteAllowlist.
+ *   G6  resolved path inside project root
+ *   G7  relative path matches an allowedPaths pattern
+ *   G8  (all passed) → allow
+ *
+ * Exit codes:  0 = allow   2 = deny
+ *
+ * SECURITY notes (inline refs):
+ *   REQ-01  top-level try/catch → emitDeny on unexpected error (fail-closed)
+ *   REQ-03  realpath(dirname) to resolve symlinks; ENOENT → fall back to path.resolve
+ *   REQ-04  relativeFromRoot() === null → deny as outside-root
+ *   REQ-05  normalize path separators to "/" before pathMatchesPattern (Windows compat)
+ *   REQ-06  relative file_path resolved against projectRoot, not process.cwd()
+ *   REQ-08  wave-scope.json read once; parsed object passed to all gate checks
+ *   REQ-09  (#792) G5b out-of-repo carveout is structurally safe: RELATIVE
+ *           allowedPaths entries can NEVER match an out-of-repo path (the
+ *           isAbsolute filter drops them), so `**` / `../**` cannot be used to
+ *           escape the repo; only entries that are themselves absolute match,
+ *           and only against their own literal (canonical/realpath) subtree.
+ *           Empty absolute set → the pre-gate is inert (byte-identical to the
+ *           pre-#792 behaviour).
+ *
+ * Coordinator carveout (#245): a short, explicit list of harness-owned files
+ * bypasses Gate 7 (allowedPaths glob) — specifically STATE.md across all platform
+ * state dirs and the wave-scope.json manifest itself. Coordinators write these
+ * between waves as part of the harness protocol; subjecting them to per-wave
+ * allowedPaths would force every wave plan to re-list harness infrastructure.
+ * Project-root containment (Gate 6) and enforcement-off (Gate 5) still apply.
+ * No wildcards — exact string match only.
+ */
+
+import path from 'node:path';
+import { promises as fs } from 'node:fs';
+
+import { shouldRunHook } from './_lib/profile-gate.mjs';
+// #211: exit 0 immediately (silent allow) when this hook is disabled via profile/env
+if (!shouldRunHook('enforce-scope')) process.exit(0);
+
+import { readStdin, emitAllow, emitDeny, emitWarn } from '../scripts/lib/io.mjs';
+import { isPathInside, relativeFromRoot } from '../scripts/lib/path-utils.mjs';
+import { resolveProjectDir } from '../scripts/lib/platform.mjs';
+import {
+  findScopeFile,
+  pathMatchesPattern,
+  suggestForScopeViolation,
+} from '../scripts/lib/hardening.mjs';
+import { readJson } from '../scripts/lib/common.mjs';
+
+async function main() {
+  // SECURITY-REQ-01: null-guard empty stdin — treat as allow (no input = not a real hook call)
+  const input = await readStdin();
+  if (!input) return emitAllow();
+
+  const toolName = input.tool_name;
+  const filePath = input?.tool_input?.file_path;
+
+  // Gate 1: only Edit, Write, and MultiEdit are path-gated
+  if (toolName !== 'Edit' && toolName !== 'Write' && toolName !== 'MultiEdit') return emitAllow();
+
+  // Gate 2: file_path must be a non-empty string
+  if (!filePath || typeof filePath !== 'string') return emitAllow();
+
+  const projectRootRaw = resolveProjectDir();
+
+  // Resolve symlinks in the project root itself so that realpath(file) comparisons
+  // are consistent. On macOS /tmp → /private/tmp; mismatches would cause false denials.
+  let projectRoot;
+  try {
+    projectRoot = await fs.realpath(projectRootRaw);
+  } catch {
+    projectRoot = projectRootRaw;
+  }
+
+  // Gate 3: no wave-scope.json → nothing to enforce
+  const scopePath = findScopeFile(projectRoot);
+  if (!scopePath) return emitAllow();
+
+  // SECURITY-REQ-08: read scope file once; pass parsed object to all subsequent checks
+  let scope;
+  try {
+    scope = await readJson(scopePath);
+  } catch {
+    scope = {};
+  }
+
+  const enforcement = scope.enforcement ?? 'strict';
+  const allowedPaths = Array.isArray(scope.allowedPaths) ? scope.allowedPaths : [];
+  const gatesEnabled = scope.gates?.['path-guard'] !== false;
+
+  // Gate 4: path-guard gate explicitly disabled
+  if (!gatesEnabled) return emitAllow();
+
+  // Gate 5: enforcement is turned off
+  if (enforcement === 'off') return emitAllow();
+
+  // SECURITY-REQ-06: resolve relative file_path against projectRoot, not process.cwd()
+  const absPathInput = path.isAbsolute(filePath)
+    ? filePath
+    : path.resolve(projectRoot, filePath);
+
+  // SECURITY-REQ-03: resolve symlinks to prevent symlink-escape.
+  // Strategy:
+  //   1. Try fs.realpath on the file itself — follows symlinks (blocks `src/evil → /etc/passwd`).
+  //   2. On ENOENT (file doesn't exist yet — common for Write), walk up to the
+  //      nearest existing ancestor, realpath it, then re-attach the non-existent
+  //      suffix. Keeps projectRoot and resolvedPath in the same canonical namespace
+  //      (e.g. both under /private/tmp on macOS).
+  //   3. Any non-ENOENT fs error → fail-closed.
+  let resolvedPath;
+  try {
+    resolvedPath = await fs.realpath(absPathInput);
+  } catch (err) {
+    if (err?.code !== 'ENOENT') {
+      return emitDeny(
+        'Scope check failed — unable to resolve file path',
+        `Internal: ${err?.code ?? 'unknown'}`,
+      );
+    }
+    // File doesn't exist yet — walk up to nearest existing ancestor.
+    try {
+      const segments = [path.basename(absPathInput)];
+      let ancestor = path.dirname(absPathInput);
+      while (true) {
+        try {
+          const realAncestor = await fs.realpath(ancestor);
+          segments.reverse();
+          resolvedPath = path.join(realAncestor, ...segments);
+          break;
+        } catch (e) {
+          if (e?.code !== 'ENOENT') throw e;
+          const parent = path.dirname(ancestor);
+          if (parent === ancestor) {
+            // Hit filesystem root (should not occur for paths under projectRoot).
+            resolvedPath = absPathInput;
+            break;
+          }
+          segments.push(path.basename(ancestor));
+          ancestor = parent;
+        }
+      }
+    } catch (e) {
+      return emitDeny(
+        'Scope check failed — unable to resolve file path',
+        `Internal: ${e?.code ?? 'unknown'}`,
+      );
+    }
+  }
+
+  // Gate 5b (#792): allowlist-first for explicit absolute (out-of-repo) grants.
+  // An EXPLICIT absolute allowedPaths entry (e.g. a coordinator-granted vault
+  // path) is structurally unreachable under Gate 6, which denies every
+  // out-of-repo path before allowedPaths is ever consulted. Honour such grants
+  // here — matching ONLY absolute entries against the fully realpath-resolved
+  // candidate, so relative entries can never be used to escape the repo (REQ-09).
+  if (matchesAbsoluteAllowlist(resolvedPath, allowedPaths)) return emitAllow();
+
+  // Gate 6: path must be inside the project root
+  if (!isPathInside(resolvedPath, projectRoot)) {
+    const reason = `Scope violation: path outside project root`;
+    const suggestion = suggestForScopeViolation(filePath, allowedPaths.join(', '));
+    return enforcement === 'strict'
+      ? emitDeny(reason, suggestion)
+      : emitWarn(`${reason} — ${suggestion}`);
+  }
+
+  // Compute the relative path from project root to the resolved file path
+  const relPath = relativeFromRoot(projectRoot, resolvedPath);
+
+  // SECURITY-REQ-04: null return means outside root — deny rather than pass null to pathMatchesPattern
+  if (relPath === null) {
+    const reason = `Scope violation: '${filePath}' outside project root`;
+    const suggestion = suggestForScopeViolation(filePath, allowedPaths.join(', '));
+    return enforcement === 'strict'
+      ? emitDeny(reason, suggestion)
+      : emitWarn(`${reason} — ${suggestion}`);
+  }
+
+  // SECURITY-REQ-05: normalize Windows path separators to '/' before glob matching
+  const normalizedRel = relPath.split(path.sep).join('/');
+
+  // Coordinator carveout (#245): exact-path allowlist for harness-owned files.
+  // STATE.md and wave-scope.json are written by the coordinator between waves;
+  // per-wave allowedPaths lists should not need to enumerate harness infrastructure.
+  if (isCoordinatorCarveout(normalizedRel, projectRoot, scopePath)) {
+    return emitAllow();
+  }
+
+  // Gate 7: check normalised relative path against each allowedPaths pattern
+  const matched = allowedPaths.some((pattern) => pathMatchesPattern(normalizedRel, pattern));
+
+  if (!matched) {
+    const reason = `Scope violation: '${normalizedRel}' not in allowed paths [${allowedPaths.join(', ')}]`;
+    const suggestion = suggestForScopeViolation(normalizedRel, allowedPaths.join(', '));
+    return enforcement === 'strict'
+      ? emitDeny(reason, suggestion)
+      : emitWarn(`${reason} — ${suggestion}`);
+  }
+
+  // Gate 8 / all gates passed → allow
+  return emitAllow();
+}
+
+const COORDINATOR_CARVEOUT_PATHS = Object.freeze([
+  '.claude/STATE.md',
+  '.codex/STATE.md',
+  '.cursor/STATE.md',
+  '.pi/STATE.md',
+]);
+
+/**
+ * Returns true if the given project-relative, forward-slash-normalized path is
+ * one of the harness-owned files the coordinator writes between waves.
+ *
+ * Matches STATE.md across all platform state dirs and the wave-scope.json the
+ * hook just read (its exact, resolved relative path — no wildcard). Exact
+ * string comparison only; any glob semantics belong in Gate 7.
+ */
+function isCoordinatorCarveout(normalizedRel, projectRoot, scopePath) {
+  if (COORDINATOR_CARVEOUT_PATHS.includes(normalizedRel)) return true;
+  const scopeRel = relativeFromRoot(projectRoot, scopePath);
+  if (scopeRel === null) return false;
+  return scopeRel.split(path.sep).join('/') === normalizedRel;
+}
+
+/**
+ * #792: Honour EXPLICIT absolute allowedPaths entries that point OUTSIDE the repo
+ * (a deliberate coordinator grant, e.g. "/Users/x/Projects/vault/**").
+ * Such entries are structurally unreachable under the default relative-only
+ * matcher because Gate 6 denies out-of-repo paths first, and Gate 7 only ever
+ * matches the ROOT-RELATIVE candidate (an absolute pattern can never match it).
+ *
+ * SECURITY (REQ-09): matches ONLY entries that are themselves absolute, against
+ * the fully realpath-resolved candidate — so RELATIVE entries (`**`, `../**`)
+ * can NEVER be used to escape the repo. When no absolute entry exists the helper
+ * returns false and the caller falls through to Gate 6 unchanged (inert pre-gate).
+ * An absolute entry matches only its own literal (canonical/realpath) subtree;
+ * the operator is responsible for supplying a canonical absolute path.
+ *
+ * @param {string} resolvedPath — fully realpath-resolved candidate (absolute)
+ * @param {string[]} allowedPaths — raw allowedPaths array from wave-scope.json
+ * @returns {boolean}
+ */
+function matchesAbsoluteAllowlist(resolvedPath, allowedPaths) {
+  const abs = allowedPaths.filter((p) => typeof p === 'string' && path.isAbsolute(p));
+  if (abs.length === 0) return false;
+  const normalizedAbs = resolvedPath.split(path.sep).join('/');
+  return abs.some((pat) => pathMatchesPattern(normalizedAbs, pat.split(path.sep).join('/')));
+}
+
+// SECURITY-REQ-01 (fail-closed): any unhandled rejection → structured deny, never bare exit 1
+main().catch((e) => {
+  emitDeny(
+    'Internal hook error — request blocked for safety',
+    `${e?.message ?? String(e)}`,
+  );
+});

package/hooks/hooks-codex.json

@@ -0,0 +1,60 @@
+{
+  "description": "Synchronous Codex hooks for payload-compatible Session Orchestrator handlers.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '🎯 Session Orchestrator v3.16.0 — /session [housekeeping|feature|deep] | /plan [new|feature|retro] | /discovery [scope] | /evolve [analyze|review|list]'",
+            "async": false
+          },
+          {
+            "type": "command",
+            "command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/on-session-start.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/loop-guard.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [],
+    "SubagentStop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/on-stop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "SO_PLATFORM=codex CODEX_PLUGIN_ROOT=\"${PLUGIN_ROOT}\" sh \"${PLUGIN_ROOT}/hooks/run-node.sh\" \"${PLUGIN_ROOT}/hooks/on-stop.mjs\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/hooks-cursor.json

@@ -0,0 +1,15 @@
+{
+  "_comment": "Cursor IDE hook mapping reference. Configure hooks in Cursor Settings > Hooks.",
+  "_note": "Cursor hooks fire at different lifecycle points than Claude Code. See docs/cursor-setup.md for details.",
+  "_limitation": "SessionStart greeting (session-start skill) is NOT available on Cursor. Cursor has no conversation-start lifecycle event equivalent to Claude Code's UserPromptSubmit hook. Session initialisation must be triggered manually.",
+  "hooks": {
+    "afterFileEdit": {
+      "script": "hooks/enforce-scope.mjs",
+      "note": "Post-hoc scope warning — Cursor fires AFTER the edit (not before). Cannot prevent out-of-scope edits, only warn."
+    },
+    "beforeShellExecution": {
+      "script": "hooks/enforce-commands.mjs",
+      "note": "Blocks dangerous commands before shell execution. Direct equivalent of Claude Code's PreToolUse Bash hook."
+    }
+  }
+}