claude-code-session-manager 0.95.0 → 0.97.0

package/scripts/hooks/guard-self-schedule.cjs

@@ -90,11 +90,7 @@
  */
 'use strict';
 
-const ALWAYS_DENY_TOOLS = new Set(['ScheduleWakeup', 'CronCreate']);
-const BACKGROUNDABLE_AGENT_TOOLS = new Set(['Task', 'Agent']);
-
-const STANDARDS_QUOTE = 'You ARE the executor — never re-queue or self-schedule.';
-const STANDARDS_CITE = 'plugins/session-manager-dev/skills/develop/standards.md:85 (Execution discipline)';
+const { decide, parsePayload } = require('./lib/guard-self-schedule-policy.cjs');
 
 function readStdin() {
   return new Promise((resolve) => {
@@ -107,69 +103,21 @@ function readStdin() {
   });
 }
 
-function allow() {
-  process.stdout.write(JSON.stringify({ continue: true }));
-  process.exit(0);
-}
-
-function deny(reason) {
-  process.stdout.write(JSON.stringify({
-    continue: true,
-    decision: 'block',
-    reason,
-    hookSpecificOutput: {
-      hookEventName: 'PreToolUse',
-      permissionDecision: 'deny',
-      permissionDecisionReason: reason,
-    },
-  }));
+function emit(result) {
+  process.stdout.write(JSON.stringify(result));
   process.exit(0);
 }
 
 async function main() {
   const raw = await readStdin();
-  let payload;
-  try {
-    payload = raw ? JSON.parse(raw) : {};
-  } catch (e) {
-    console.error(`[guard-self-schedule] malformed stdin JSON, failing open: ${e?.message}`);
-    return allow();
-  }
-
-  try {
-    const jobSlug = process.env.SM_SCHEDULER_JOB_SLUG;
-    if (!jobSlug) return allow(); // interactive session — this guard is inert here
-
-    const toolName = payload.tool_name;
-
-    if (ALWAYS_DENY_TOOLS.has(toolName)) {
-      const reason = [
-        `Blocked: \`${toolName}\` from inside a headless scheduler-spawned run (job '${jobSlug}').`,
-        `${STANDARDS_CITE}: "${STANDARDS_QUOTE}"`,
-        'A headless run has no next turn — nothing will ever deliver this wakeup, so the job exits with its work stranded and parks in needs_review even if it was already correct.',
-        'Do it now instead: commit what you have, then run any required review synchronously inline (call the reviewer and read its result in this same turn) before the finish protocol — never schedule it for later.',
-      ].join(' ');
-      return deny(reason);
-    }
-
-    if (BACKGROUNDABLE_AGENT_TOOLS.has(toolName) && payload.tool_input && payload.tool_input.run_in_background) {
-      const reason = [
-        `Blocked: a backgrounded ${toolName} call (run_in_background: true) from inside a headless scheduler-spawned run (job '${jobSlug}').`,
-        `${STANDARDS_CITE}: "${STANDARDS_QUOTE}"`,
-        'A headless run has no later turn to collect a background agent\'s result, so waiting on it (ListAgents, Monitor, ScheduleWakeup) strands the job in needs_review with its work already done but uncommitted.',
-        'Call it synchronously instead — omit run_in_background (or set it to false) and read its result in this same turn, before the finish protocol.',
-      ].join(' ');
-      return deny(reason);
-    }
-
-    return allow();
-  } catch (e) {
-    console.error(`[guard-self-schedule] internal error, failing open: ${e?.message}`);
-    return allow();
-  }
+  return emit(decide(parsePayload(raw)));
 }
 
+// Runs as a require-time side effect, NOT gated on `require.main === module`
+// — see src/main/lib/guardShims.cjs's header: the installed shim invokes this
+// script via a plain `require()`, so gating on `require.main` would silently
+// stop the shim from ever running the guard.
 main().catch((e) => {
   console.error(`[guard-self-schedule] unhandled error, failing open: ${e?.message}`);
-  allow();
+  emit({ continue: true });
 });

package/scripts/hooks/lib/guard-destructive-git-policy.cjs

@@ -0,0 +1,410 @@
+/**
+ * guard-destructive-git-policy.cjs — decision logic for
+ * scripts/hooks/guard-destructive-git.cjs, split out so it can be
+ * `require()`d in-process (by tests, notably) with no CLI-level side effects.
+ *
+ * guard-destructive-git.cjs itself runs its CLI as a require-time side
+ * effect (stdin -> decision -> process.exit, not gated on
+ * `require.main === module` — see src/main/lib/guardShims.cjs's header for
+ * why: the installed shim invokes the real script via a plain `require()`,
+ * so gating on `require.main` would silently stop the shim from ever running
+ * the guard). Requiring THIS module never reads stdin or calls
+ * `process.exit`, so it's safe to load from a test process — but `decide()`
+ * is not fully I/O-free: for a destructive verdict outside a
+ * path-recognized managed worktree, it shells out to a real `git
+ * rev-parse` (see `isInsideManagedWorktreeByBranch` below) before returning.
+ * Most `expectDenied(...)` cases in the test file hit this, so most test
+ * runs still spawn a `git` child process per denied case — fewer spawns
+ * than the old ~50-CLI-process-per-run shape, not zero.
+ */
+'use strict';
+
+const path = require('node:path');
+const os = require('node:os');
+const { execFileSync } = require('node:child_process');
+
+// Duplicated from src/main/lib/gitWorktree.cjs's KIND_CONFIG — see
+// guard-destructive-git.cjs's header for why this is a deliberate
+// duplication, not a require. Same SM_WORKTREE_ROOT-else-tmpdir base as
+// schedulerPaths.worktreeBase().
+const WORKTREE_BASE = process.env.SM_WORKTREE_ROOT || os.tmpdir();
+const WORKTREE_ROOTS = ['job', 'epic'].map((k) => path.join(WORKTREE_BASE, `session-manager-${k}-worktrees`));
+const BRANCH_PREFIXES = ['sm-job/', 'sm-epic/'];
+
+const MAX_SH_C_DEPTH = 5;
+
+/** Quote-aware split on top-level `&&`, `||`, `;`, `|`, and newlines. */
+function splitTopLevel(cmd) {
+  const parts = [];
+  let cur = '';
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < cmd.length; i++) {
+    const c = cmd[i];
+    if (inSingle) {
+      cur += c;
+      if (c === "'") inSingle = false;
+      continue;
+    }
+    if (inDouble) {
+      cur += c;
+      if (c === '"' && cmd[i - 1] !== '\\') inDouble = false;
+      continue;
+    }
+    if (c === "'") { inSingle = true; cur += c; continue; }
+    if (c === '"') { inDouble = true; cur += c; continue; }
+    const two = cmd.slice(i, i + 2);
+    if (two === '&&' || two === '||') { parts.push(cur); cur = ''; i++; continue; }
+    if (c === ';' || c === '|' || c === '\n') { parts.push(cur); cur = ''; continue; }
+    cur += c;
+  }
+  parts.push(cur);
+  return { parts: parts.map((s) => s.trim()).filter(Boolean), unterminatedQuote: inSingle || inDouble };
+}
+
+/** Quote-aware whitespace tokenizer. Returns null on an unterminated quote. */
+function tokenize(str) {
+  const tokens = [];
+  let cur = '';
+  let started = false;
+  let inSingle = false;
+  let inDouble = false;
+  for (let i = 0; i < str.length; i++) {
+    const c = str[i];
+    if (inSingle) {
+      if (c === "'") inSingle = false; else cur += c;
+      started = true;
+      continue;
+    }
+    if (inDouble) {
+      if (c === '"') inDouble = false; else cur += c;
+      started = true;
+      continue;
+    }
+    if (c === "'") { inSingle = true; started = true; continue; }
+    if (c === '"') { inDouble = true; started = true; continue; }
+    if (/\s/.test(c)) {
+      if (started) { tokens.push(cur); cur = ''; started = false; }
+      continue;
+    }
+    cur += c;
+    started = true;
+  }
+  if (started) tokens.push(cur);
+  if (inSingle || inDouble) return null;
+  return tokens;
+}
+
+function isFlagWithChar(rest, longForms, shortChar) {
+  for (const t of rest) {
+    if (longForms.includes(t)) return true;
+    if (shortChar && t.startsWith('-') && !t.startsWith('--') && t.includes(shortChar)) return true;
+  }
+  return false;
+}
+
+/** Skip git's global options (`-C <dir>`, `-c <k>=<v>`, `--git-dir=...`, ...) to find the subcommand. */
+function subcommandOf(args) {
+  const OPTS_WITH_SEPARATE_ARG = new Set(['-C', '-c', '--namespace', '--super-prefix']);
+  let i = 0;
+  while (i < args.length) {
+    const t = args[i];
+    if (OPTS_WITH_SEPARATE_ARG.has(t)) { i += 2; continue; }
+    if (t.startsWith('-')) { i += 1; continue; }
+    return { subcommand: t, rest: args.slice(i + 1) };
+  }
+  return null;
+}
+
+/** Extract an explicit `git -C <dir>` argument (or `git -C=<dir>`), if present, from the tokens AFTER `git`. */
+function gitDashCDirOf(args) {
+  for (let i = 0; i < args.length; i++) {
+    const t = args[i];
+    if (t === '-C' && args[i + 1] != null) return args[i + 1];
+    if (t.startsWith('-C') && t.length > 2) return t.slice(2);
+    if (!t.startsWith('-')) break; // reached the subcommand — no more global opts
+  }
+  return null;
+}
+
+/**
+ * Text-level check for whether an UNPARSABLE segment mentions a verb this
+ * guard actually polices. Used only to narrow the unparsable-command fallback
+ * — an unparsable command that mentions none of these is allowed through
+ * rather than blanket-blocked, since blocking every command merely containing
+ * the substring "git" (e.g. a heredoc `git commit -m "$(cat <<'EOF' ...)"`)
+ * was itself a false-positive incident.
+ */
+function mentionsPolicedDestructiveToken(text) {
+  if (/\b(stash|reset|checkout|restore|clean)\b/.test(text)) return true;
+  if (/\badd\s+(-A\b|--all\b|\.(?:\s|$))/.test(text)) return true;
+  if (/\bcommit\b.*(-a\b|--all\b)/.test(text)) return true;
+  return false;
+}
+
+/**
+ * Evaluate one `git <...>` invocation (args = tokens AFTER `git`). Returns
+ * `{ verb, alt }` when destructive, or null when this invocation is fine
+ * (read-only, or a form this guard doesn't restrict).
+ */
+function evaluateGit(args) {
+  const parsed = subcommandOf(args);
+  if (!parsed) return null;
+  const { subcommand, rest } = parsed;
+
+  switch (subcommand) {
+    case 'stash': {
+      const sub = rest.find((a) => !a.startsWith('-'));
+      if (sub === 'list' || sub === 'show') return null;
+      return {
+        verb: 'git stash',
+        alt: 'do not stash on a shared tree — a stash you never restore silently strands someone else\'s work; commit or discard only paths you created, or stop and report',
+      };
+    }
+    case 'reset': {
+      const hasHard = rest.includes('--hard');
+      const positional = rest.filter((a) => !a.startsWith('-'));
+      if (hasHard) {
+        return {
+          verb: 'git reset --hard',
+          alt: 'never hard-reset a shared tree — this discards a sibling job\'s or the human\'s uncommitted work outright; undo only your own change with `git checkout -- <your-path>` inside your own sm-job/ or sm-epic/ worktree, or stop and report',
+        };
+      }
+      if (positional.length > 0) {
+        return {
+          verb: 'git reset <path>',
+          alt: 'do not `git reset` a path on a shared tree — that can unstage a sibling job\'s or the human\'s in-progress staging, not just your own',
+        };
+      }
+      return null;
+    }
+    case 'checkout': {
+      const dashIdx = rest.indexOf('--');
+      if (dashIdx !== -1 && rest.slice(dashIdx + 1).length > 0) {
+        return {
+          verb: 'git checkout -- <path>',
+          alt: 'never discard tracked-file edits on a shared tree with `checkout --` — that can erase a sibling job\'s or the human\'s uncommitted work; scope changes to files you created, or stop and report',
+        };
+      }
+      // `.` is never a valid branch/commit name, so `git checkout .` (no
+      // `--` at all) is unambiguously the pathspec form — and, like
+      // `checkout -- .`, discards every dirty tracked file in the tree. Git
+      // accepts this bare form; requiring `--` before flagging it let this
+      // exact incident shape (real precedent: `starry-night-ships`, see
+      // guard-destructive-git.cjs's header) walk straight past the guard.
+      const positional = rest.filter((a) => a !== '--' && !a.startsWith('-'));
+      if (positional.includes('.')) {
+        return {
+          verb: 'git checkout .',
+          alt: 'never discard tracked-file edits on a shared tree with `checkout .` — that can erase a sibling job\'s or the human\'s uncommitted work; scope changes to files you created, or stop and report',
+        };
+      }
+      return null;
+    }
+    case 'restore': {
+      if (rest.includes('-n') || rest.includes('--dry-run')) return null;
+      const positional = rest.filter((a) => !a.startsWith('-'));
+      if (positional.length > 0) {
+        return {
+          verb: 'git restore',
+          alt: 'never `git restore` tracked paths on a shared tree — that discards whatever is currently dirty there, which may not be yours',
+        };
+      }
+      return null;
+    }
+    case 'clean': {
+      if (isFlagWithChar(rest, ['--dry-run'], 'n')) return null;
+      const hasF = isFlagWithChar(rest, ['--force'], 'f');
+      const hasD = isFlagWithChar(rest, [], 'd');
+      const hasX = isFlagWithChar(rest, [], 'x');
+      if (hasF || hasD || hasX) {
+        return {
+          verb: 'git clean -f/-d/-x',
+          alt: 'never force-clean a shared tree — that deletes files git doesn\'t track, which may be a sibling job\'s scratch output or the human\'s untracked WIP',
+        };
+      }
+      return null;
+    }
+    case 'add': {
+      const hasBlanket = rest.some((a) => a === '-A' || a === '--all' || a === '.');
+      if (hasBlanket) {
+        return {
+          verb: 'git add -A/./--all',
+          alt: 'stage only the exact paths you created or modified — `git add <path> [<path>...]` — a blanket add on a shared tree captures a sibling job\'s or the human\'s in-progress edits and mis-attributes them to your commit',
+        };
+      }
+      return null;
+    }
+    case 'commit': {
+      const hasAll = isFlagWithChar(rest, ['--all'], 'a');
+      if (hasAll) {
+        return {
+          verb: 'git commit -a',
+          alt: 'commit only the paths you explicitly `git add`ed — `git commit -a`/`--all` on a shared tree sweeps up whatever a sibling job or the human currently has dirty',
+        };
+      }
+      return null;
+    }
+    default:
+      return null;
+  }
+}
+
+const SH_WRAPPERS = new Set(['sh', 'bash', 'zsh', 'dash']);
+
+/**
+ * Returns the first destructive verdict found anywhere in `command`, or null.
+ * `baseCwd` is the shell's starting cwd; a `cd <dir>` segment updates the
+ * EFFECTIVE cwd for every subsequent segment in the same top-level command
+ * (segments share one shell), and an explicit `git -C <dir>` overrides it for
+ * that one invocation only. The returned verdict carries the effective cwd at
+ * the point the destructive call was found, so the caller checks exemption
+ * against where the command actually runs, not just `payload.cwd`.
+ */
+function findDestructiveVerdict(command, baseCwd, depth = 0) {
+  if (depth > MAX_SH_C_DEPTH) return null;
+  const { parts, unterminatedQuote } = splitTopLevel(command);
+  if (unterminatedQuote) {
+    if (mentionsPolicedDestructiveToken(command)) {
+      return { verb: 'an unparsable command mentioning git', alt: 'this hook could not confidently parse this command\'s quoting to confirm it is safe — split it into a plain, simply-quoted git invocation, or stop and report', cwd: baseCwd };
+    }
+    return null;
+  }
+
+  let effectiveCwd = baseCwd;
+
+  for (const segment of parts) {
+    const tokens = tokenize(segment);
+    if (tokens === null) {
+      if (mentionsPolicedDestructiveToken(segment)) {
+        return { verb: 'an unparsable command mentioning git', alt: 'this hook could not confidently parse this command\'s quoting to confirm it is safe — split it into a plain, simply-quoted git invocation, or stop and report', cwd: effectiveCwd };
+      }
+      continue;
+    }
+    if (tokens.length === 0) continue;
+
+    // Strip leading env assignments (FOO=bar git ...).
+    let i = 0;
+    while (i < tokens.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(tokens[i])) i++;
+    const cmdTokens = tokens.slice(i);
+    if (cmdTokens.length === 0) continue;
+
+    const head = path.basename(cmdTokens[0]);
+
+    if (head === 'cd' && cmdTokens[1] != null) {
+      const target = cmdTokens[1];
+      effectiveCwd = path.isAbsolute(target) ? target : path.resolve(effectiveCwd || process.cwd(), target);
+      continue;
+    }
+
+    if (SH_WRAPPERS.has(head)) {
+      const cIdx = cmdTokens.indexOf('-c');
+      if (cIdx !== -1 && cmdTokens[cIdx + 1] != null) {
+        const nested = findDestructiveVerdict(cmdTokens[cIdx + 1], effectiveCwd, depth + 1);
+        if (nested) return nested;
+      }
+      continue;
+    }
+
+    if (head === 'git') {
+      const gitArgs = cmdTokens.slice(1);
+      const verdict = evaluateGit(gitArgs);
+      if (verdict) {
+        const dashC = gitDashCDirOf(gitArgs);
+        const invocationCwd = dashC
+          ? (path.isAbsolute(dashC) ? dashC : path.resolve(effectiveCwd || process.cwd(), dashC))
+          : effectiveCwd;
+        return { ...verdict, cwd: invocationCwd };
+      }
+    }
+  }
+  return null;
+}
+
+function isInsideManagedWorktreeByPath(cwd) {
+  if (!cwd) return false;
+  const resolved = path.resolve(cwd);
+  return WORKTREE_ROOTS.some((root) => resolved === root || resolved.startsWith(root + path.sep));
+}
+
+function isInsideManagedWorktreeByBranch(cwd) {
+  if (!cwd) return false;
+  try {
+    const branch = execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+      cwd,
+      timeout: 3_000,
+      encoding: 'utf8',
+      windowsHide: true,
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+    return BRANCH_PREFIXES.some((p) => branch.startsWith(p));
+  } catch {
+    return false;
+  }
+}
+
+function isExemptSharedTree(cwd) {
+  return isInsideManagedWorktreeByPath(cwd) || isInsideManagedWorktreeByBranch(cwd);
+}
+
+function buildAllow() {
+  return { continue: true };
+}
+
+function buildDeny(reason) {
+  return {
+    continue: true,
+    decision: 'block',
+    reason,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/**
+ * Decision function: PreToolUse payload in, hook-response object out. No
+ * stdin/stdout and no `process.exit` — safe to call in-process (e.g. from
+ * tests) — but for a destructive verdict outside a path-recognized managed
+ * worktree it does shell out to `git rev-parse` (see
+ * `isInsideManagedWorktreeByBranch`); it is not I/O-free in that case.
+ */
+function decide(payload) {
+  try {
+    if (payload.tool_name !== 'Bash') return buildAllow();
+
+    const command = payload?.tool_input?.command;
+    if (!command || typeof command !== 'string') return buildAllow();
+
+    const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+    const verdict = findDestructiveVerdict(command, cwd);
+    if (!verdict) return buildAllow();
+
+    const effectiveCwd = verdict.cwd || cwd;
+    if (isExemptSharedTree(effectiveCwd)) return buildAllow();
+
+    const reason = [
+      `Blocked: \`${verdict.verb}\` in what this hook believes is a SHARED working tree (${effectiveCwd}).`,
+      verdict.alt,
+      'You are normally inside your own sm-job/<slug> or sm-epic/<epicId> worktree for this kind of operation — run `git rev-parse --git-common-dir` to check; this guard permits the same command there.',
+    ].join(' ');
+    return buildDeny(reason);
+  } catch (e) {
+    console.error(`[guard-destructive-git] internal error, failing open: ${e?.message}`);
+    return buildAllow();
+  }
+}
+
+/** Mirrors the CLI's stdin-JSON handling so it can be exercised without a spawn. */
+function parsePayload(raw) {
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    console.error(`[guard-destructive-git] malformed stdin JSON, failing open: ${e?.message}`);
+    return {};
+  }
+}
+
+module.exports = { decide, parsePayload };

package/scripts/hooks/lib/guard-inline-implementation-policy.cjs

@@ -0,0 +1,159 @@
+/**
+ * guard-inline-implementation-policy.cjs — decision logic for
+ * scripts/hooks/guard-inline-implementation.cjs, split out so it can be
+ * `require()`d in-process (by tests, notably) with no CLI-level side effects.
+ *
+ * guard-inline-implementation.cjs itself runs its CLI as a require-time side
+ * effect (stdin -> decision -> process.exit, not gated on
+ * `require.main === module` — see its header for why). Requiring THIS module
+ * never reads stdin or calls `process.exit`, so it's safe to load from a test
+ * process — but `decide()` is not I/O-free: it reads
+ * `<cwd>/session-manager-operations/prompt-sessions/active-index.json` off
+ * disk and, when the Epic runs in a linked worktree, shells out to a real
+ * `git rev-parse` to resolve the ops root (see `resolveOpsRootCwd` below).
+ * Calling it directly from a test still removes the outer CLI-process spawn
+ * per case, exercising real filesystem/git behavior instead of mocking it.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+// Pure fs helper only — deliberately NOT gitWorktree (keeps this guard light).
+const { nearestGitEntry } = require('../../../src/main/lib/cwdClassify.cjs');
+
+const SOURCE_DIRS = ['src', 'scripts', 'plugins', 'bin'];
+const DENY_TAGS = new Set(['feature', 'bug']);
+
+function targetPathFor(toolName, toolInput) {
+  if (!toolInput || typeof toolInput !== 'object') return null;
+  if (toolName === 'NotebookEdit') return toolInput.notebook_path ?? null;
+  return toolInput.file_path ?? null;
+}
+
+function isApplicationSource(cwd, absPath) {
+  const rel = path.relative(cwd, absPath);
+  if (rel.startsWith('..') || path.isAbsolute(rel)) return false; // outside cwd
+  const topLevel = rel.split(path.sep)[0];
+  return SOURCE_DIRS.includes(topLevel);
+}
+
+/**
+ * The PreToolUse payload's `cwd` is the CLI process's actual spawn cwd. For
+ * an Epic running in its default isolated `git worktree` (gitWorktree.cjs,
+ * epicSpawnCwd.cjs — "both the Terminal PTY and headless Chat spawn cwd
+ * resolve to it"), that is a throwaway checkout under os.tmpdir(), which
+ * never contains `session-manager-operations/` — the ops root always lives
+ * in the real project tree (see gitWorktree.cjs's "ops-root hazard" header:
+ * "spawn cwd = worktree dir, ops-root cwd = real project cwd, always").
+ * Resolve back to the real project cwd via git's shared `.git` dir before
+ * giving up, so this guard isn't silently inert for every Epic running in
+ * its default worktree.
+ */
+function resolveOpsRootCwd(rawCwd) {
+  if (fs.existsSync(path.join(rawCwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json'))) {
+    return rawCwd;
+  }
+  try {
+    // Only a `.git` FILE (linked worktree) needs git to find the shared dir; a
+    // `.git` directory IS the project root, so skip the spawn.
+    const entry = nearestGitEntry(rawCwd);
+    if (!entry) return rawCwd;
+    if (!entry.isFile) return entry.dir;
+    const commonDir = execFileSync(
+      'git',
+      ['rev-parse', '--path-format=absolute', '--git-common-dir'],
+      { cwd: rawCwd, encoding: 'utf8', timeout: 5000 },
+    ).trim();
+    if (!commonDir) return rawCwd;
+    return path.basename(commonDir) === '.git' ? path.dirname(commonDir) : commonDir;
+  } catch {
+    return rawCwd;
+  }
+}
+
+function resolveEpicTag(cwd, sessionId) {
+  if (!sessionId) return null;
+  const indexPath = path.join(cwd, 'session-manager-operations', 'prompt-sessions', 'active-index.json');
+  if (!fs.existsSync(indexPath)) return null;
+  const raw = fs.readFileSync(indexPath, 'utf8');
+  const index = JSON.parse(raw);
+  const sessions = index && typeof index === 'object' ? index.sessions : null;
+  if (!sessions || typeof sessions !== 'object') return null;
+  for (const record of Object.values(sessions)) {
+    if (record && record.claudeSessionId === sessionId) return record;
+  }
+  return null;
+}
+
+function buildAllow() {
+  return { continue: true };
+}
+
+function buildDeny(reason) {
+  return {
+    continue: true,
+    decision: 'block',
+    reason,
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecision: 'deny',
+      permissionDecisionReason: reason,
+    },
+  };
+}
+
+/**
+ * Decision function: PreToolUse payload in, hook-response object out. No
+ * stdin/stdout and no `process.exit` — safe to call in-process (e.g. from
+ * tests) — but does real filesystem reads and, in the linked-worktree case, a
+ * real `git rev-parse` spawn (see `resolveOpsRootCwd`).
+ */
+function decide(payload) {
+  try {
+    if (process.env.SM_ALLOW_INLINE_IMPLEMENTATION === '1') return buildAllow();
+
+    const toolName = payload.tool_name;
+    if (toolName !== 'Write' && toolName !== 'Edit' && toolName !== 'NotebookEdit') {
+      return buildAllow();
+    }
+
+    const rawPath = targetPathFor(toolName, payload.tool_input);
+    if (!rawPath || typeof rawPath !== 'string') return buildAllow();
+
+    const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd();
+    const absPath = path.isAbsolute(rawPath) ? rawPath : path.resolve(cwd, rawPath);
+
+    if (!isApplicationSource(cwd, absPath)) return buildAllow();
+
+    const sessionId = typeof payload.session_id === 'string' ? payload.session_id : null;
+    const opsRootCwd = resolveOpsRootCwd(cwd);
+    const epic = resolveEpicTag(opsRootCwd, sessionId);
+    if (!epic) return buildAllow(); // unresolvable session — allow by construction
+
+    if (epic.allowInlineImplementation) return buildAllow();
+    if (!DENY_TAGS.has(epic.tag)) return buildAllow();
+
+    const reason = [
+      `Direct ${toolName} to application source ("${path.relative(cwd, absPath)}") is discouraged inside a "${epic.tag}" Epic.`,
+      'Feature and bug work should be decomposed and queued via /develop rather than implemented inline, so it runs through the scheduler with acceptance criteria and review.',
+      'If this inline edit is deliberate, set SM_ALLOW_INLINE_IMPLEMENTATION=1 in the environment, or set allowInlineImplementation: true on this Epic\'s record in active-index.json, and retry.',
+    ].join(' ');
+    return buildDeny(reason);
+  } catch (e) {
+    console.error(`[guard-inline-implementation] internal error, failing open: ${e?.message}`);
+    return buildAllow();
+  }
+}
+
+/** Mirrors the CLI's stdin-JSON handling so it can be exercised without a spawn. */
+function parsePayload(raw) {
+  try {
+    return raw ? JSON.parse(raw) : {};
+  } catch (e) {
+    console.error(`[guard-inline-implementation] malformed stdin JSON, failing open: ${e?.message}`);
+    return {};
+  }
+}
+
+module.exports = { decide, parsePayload };