msd-core/hooks/msd-worktree-path-guard.js

#!/usr/bin/env node
// msd-hook-version: {{MSD_VERSION}}
// MSD Worktree Path Guard — PreToolUse hook
// Blocks Edit/Write/MultiEdit tool calls that target absolute paths outside the worktree root.
//
// Problem: msd-executor agents spawned with isolation="worktree" sometimes issue
// Edit/Write calls with absolute paths rooted at the MAIN repository instead of
// the worktree (issue #260). The prose guard in agents/msd-executor.md step 0b
// is never enforced because the model under load skips it.
//
// This hook enforces the constraint at the tooling layer, making it HARD-BLOCKING.
//
// Triggers on: Edit, Write, and MultiEdit tool calls
// Action: BLOCK (exit 2) if file_path is absolute and outside the worktree root
// No-op: relative paths, non-worktree CWDs, hook errors (silent fail)

const fs = require('fs');
const path = require('path');
const { spawnSync } = require('child_process');
const { HOOK_ON_CRASH, allow, deny, crash } = require('./lib/hook-exit.js');
const { reportIfUndetermined } = require('./lib/git-probe.js');

// This guard's outer catch has always exited 0 (fail open): a path guard that
// cannot resolve the worktree must not block the user's edit — its whole job
// is a targeted containment check, not a general-purpose file-write blocker,
// and an unresolved worktree root gives it nothing to check against. Declared
// ONCE here so the outer catch's crash() call states its policy explicitly
// rather than inheriting a default (#3911).
const ON_CRASH = HOOK_ON_CRASH.ALLOW;

const SPAWNOPT = { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, windowsHide: true };

function git(args, cwd) {
  return spawnSync('git', args, { ...SPAWNOPT, cwd });
}

// Walk up from `start` to find the nearest existing directory.
// Returns null if we reach the filesystem root without finding one.
function nearestExistingDir(start) {
  let dir = start;
  let prev;
  do {
    prev = dir;
    try { fs.accessSync(dir, fs.constants.F_OK); return dir; } catch { /* keep walking */ }
    dir = path.dirname(dir);
  } while (dir !== prev);
  return null;
}

let input = '';
const stdinTimeout = setTimeout(() => allow(undefined), 3000);
process.stdin.setEncoding('utf8');
process.stdin.on('data', chunk => input += chunk);
process.stdin.on('end', () => {
  clearTimeout(stdinTimeout);
  try {
    const data = JSON.parse(input);
    const toolName = data.tool_name;

    // Only guard Edit, Write, and MultiEdit tool calls
    if (toolName !== 'Edit' && toolName !== 'Write' && toolName !== 'MultiEdit') {
      allow(undefined);
    }

    const cwd = data.cwd || process.cwd();

    // Detect whether CWD is inside a linked git worktree by inspecting
    // the git-dir path. In a linked worktree, git rev-parse --git-dir
    // returns a path containing .git/worktrees/ as a component.
    // In the main repo or a submodule it returns .git (or a path without /worktrees/).
    // This approach works even when cwd is a subdirectory of the worktree.
    // Combined into one spawn — git rev-parse accepts multiple query flags in
    // one invocation and prints one line of output per flag, in the exact
    // order given, reducing this guard's worst-case subprocess count under
    // CI/load contention (three spawns collapse into one). `--abbrev-ref HEAD`
    // is used instead of `symbolic-ref --short HEAD` because it is combinable
    // (a single `rev-parse` call) and behaviorally equivalent for this guard's
    // branch-acceptance check, including on detached HEAD: `--abbrev-ref`
    // returns the literal string `HEAD` there (exit 0), which the acceptance
    // regex below also rejects — the same guard outcome as symbolic-ref's
    // exit-128/empty-stdout failure. Do not change any timeout value as part
    // of this change, only the spawn count.
    const combinedResult = git(['rev-parse', '--git-dir', '--abbrev-ref', 'HEAD', '--show-toplevel'], cwd);
    // #3911: a timeout/spawn-failure result is indistinguishable from a clean
    // "not a git repo" answer by status/stdout alone — reportIfUndetermined
    // is a no-op on a genuine negative and only fires the diagnostic when the
    // probe itself could not run. The allow() below is UNCHANGED either way.
    reportIfUndetermined(
      'msd-worktree-path-guard',
      'git rev-parse --git-dir --abbrev-ref HEAD --show-toplevel',
      combinedResult
    );
    if (combinedResult.status !== 0 || !combinedResult.stdout) {
      allow(undefined); // not a git repo — pass through
    }

    const combinedLines = combinedResult.stdout.split('\n').map((l) => l.trim()).filter((l) => l.length > 0);
    if (combinedLines.length < 3) {
      allow(undefined); // malformed/short output — can't determine root, fail open
    }
    const [gitDir, branch, wtTopRaw] = combinedLines;

    // A linked worktree's --git-dir contains .git/worktrees/ as a path component
    const isLinkedWorktree = /[/\\]\.git[/\\]worktrees[/\\]/.test(gitDir);
    if (!isLinkedWorktree) {
      allow(undefined); // main repo, submodule, or separate-git-dir — no-op
    }

    // #1342: Only enforce inside a MSD-managed isolated executor worktree. Those
    // are always on an `agent-*` or legacy `worktree-agent-*` branch (the positive
    // allow-list enforced by worktree-branch-check.md, #2924, #1995). A manually-
    // created linked worktree (plain non-MSD work, e.g. Claude Code plan-mode) is
    // on the user's own branch, so the guard must be a no-op there. Detached HEAD
    // / error → not MSD-managed → no-op.
    // #3021: accept worktree-wf_<runid>-<n> branches (Workflow backend's naming).
    if (!/^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$/.test(branch)) {
      allow(undefined); // not a MSD-managed executor worktree — no-op
    }

    // wtTopRaw: the raw --show-toplevel output for the worktree (cwd).
    // We keep it raw (not path.resolve'd) to compare directly with the
    // file's toplevel — same git binary, same format, no normalization needed.

    // #2595 (review Major 3): read the field TYPED. `?.file_path || ''` let a
    // non-string through — `[]` and `{}` are truthy, so they survived the
    // `!rawFilePath` check and threw inside path.isAbsolute() below, landing in
    // this script's outer `catch { process.exit(0) }`. That is the same
    // crash-to-allow #2547 closes elsewhere, reached through the guard's own
    // read: `{"tool_name":"Edit", "tool_input":{"file_path":[]}}` reached it
    // untouched — this guard's original #260 surface.
    const rawFilePath = typeof data.tool_input?.file_path === 'string'
      ? data.tool_input.file_path
      : '';
    if (!rawFilePath) {
      allow(undefined);
    }

    // Relative paths resolve against the tool's CWD, which is inside the worktree
    // — so under the runtime this guard was written for they cannot leave it.
    //
    // #2595 (review Minor 5) — state the premise rather than leave it implicit.
    // "Always safe" holds only while every runtime reaching here either rejects
    // relative paths or resolves them against the worktree CWD. Claude Code's
    // Edit/Write require an absolute file_path, so the original #260 surface
    // satisfies it by construction. A runtime whose edit tool resolves relative
    // paths against anything other than the tool CWD would let a `../`-laden
    // path exit 0 at this line and escape the worktree.
    if (!path.isAbsolute(rawFilePath)) {
      allow(undefined);
    }

    // Normalise .. traversal so /worktree/src/../../../main/file
    // resolves to its true location before we check containment.
    const filePath = path.resolve(rawFilePath);

    // Find the nearest existing ancestor of filePath so we can ask git
    // for its toplevel. The file itself may not exist yet (Write creates
    // new files), but at least one ancestor directory must exist.
    // We check the file itself first in case it already exists.
    const checkDir = nearestExistingDir(
      (() => {
        try {
          return fs.statSync(filePath).isDirectory() ? filePath : path.dirname(filePath);
        } catch {
          return path.dirname(filePath);
        }
      })()
    );

    if (!checkDir) {
      // Walked to root without finding any directory — path is synthetic.
      // A path with no existing ancestor is not the #260 main-repo vector;
      // #260 is caught by the different-git-root branch below. Fail open. (#1342)
      allow(undefined);
    }

    // Ask git for the toplevel of the file's location.
    // Comparing two raw git --show-toplevel outputs avoids every
    // platform-specific path normalisation pitfall (Windows 8.3 short names,
    // case differences between realpathSync and path.resolve, forward- vs
    // back-slash inconsistencies) — both values come from the same git binary
    // in the same format by definition.
    const fileTopResult = git(['rev-parse', '--show-toplevel'], checkDir);
    reportIfUndetermined('msd-worktree-path-guard', 'git rev-parse --show-toplevel (file location)', fileTopResult);

    if (fileTopResult.status !== 0 || !fileTopResult.stdout) {
      // The target's location is not a git work tree. Two sub-cases:
      //  - Inside a .git directory (e.g. /main-repo/.git/config or .git/hooks/*)
      //    → an absolute write into a repository's internals; still a #260-class
      //    escape (and dangerous) → BLOCK.
      //  - Truly outside all git repositories (e.g. ~/.claude/plans/) → not the
      //    main-repo vector → fail open. (#1342)
      const insideGitDir = git(['rev-parse', '--is-inside-git-dir'], checkDir);
      reportIfUndetermined('msd-worktree-path-guard', 'git rev-parse --is-inside-git-dir', insideGitDir);
      if (insideGitDir.status === 0 && insideGitDir.stdout && insideGitDir.stdout.trim() === 'true') {
        const output = {
          decision: 'block',
          reason:
            `Worktree path guard: '${filePath}' is inside a git internal (.git) directory, ` +
            `not the active worktree at '${wtTopRaw}'. Writing to repository internals via an ` +
            `absolute path is not permitted from an isolated executor worktree. Use a relative path.`,
        };
        deny(output, output.reason);
      }
      // Outside all git repositories — fail open (#1342).
      allow(undefined);
    }

    const fileTopRaw = fileTopResult.stdout.trim();

    // Same git toplevel → file is inside the worktree → allow
    if (fileTopRaw === wtTopRaw) {
      allow(undefined);
    }

    // BLOCK: file resolves to a different git root than the active worktree
    const output = {
      decision: 'block',
      reason:
        `Worktree path guard: '${filePath}' resolves to git root '${fileTopRaw}' which ` +
        `differs from the active worktree root '${wtTopRaw}'. This likely means an ` +
        `absolute path was derived from the orchestrator's main repository instead of ` +
        `the active worktree. To fix: use a relative path, or re-derive the base ` +
        `directory with \`git rev-parse --show-toplevel\` from within the worktree ` +
        `(hook cwd: '${cwd}').`,
    };

    deny(output, output.reason);
  } catch {
    // Silent fail — never block valid tool calls due to hook errors.
    // ON_CRASH is declared ALLOW at module top: this preserves today's
    // exit(0) fail-open behavior exactly (#3911).
    crash(ON_CRASH, undefined);
  }
});