@bridge_gpt/mcp-server 0.2.51 → 0.2.52

package/build/executor/worker-guard-hook.js

@@ -0,0 +1,939 @@
+/**
+ * Deterministic PreToolUse worker guard (BAPI-1020, Architecture Miss 28 Slice B).
+ *
+ * The deny layer in `permissions.ts` expresses everything a GLOB can express: a
+ * command family is denied outright, or it is not. This module expresses what a
+ * glob cannot — the argument-sensitive half of the same policy:
+ *
+ *   - "push only to YOUR OWN branch" (not `main`, not a tag, not a deletion);
+ *   - "reset --hard only against YOUR OWN ref";
+ *   - "`git clean` / `rm -rf` only INSIDE your worktree";
+ *   - "no `DROP` / `TRUNCATE` through `psql` or `pg_*`";
+ *   - "no mutating `curl` / `wget`".
+ *
+ * None of those is a string match on a command name; each is a question about
+ * where an argument POINTS. A glob that tried would have to be a path glob, and a
+ * path glob is exactly what Architecture Miss 23 forbids here.
+ *
+ * Three properties define this module, and each is load-bearing:
+ *
+ * 1. DETERMINISTIC. No model call, no network, no filesystem read, no subprocess.
+ *    The same payload always produces the same decision, so a denial is auditable
+ *    and a test can pin it exactly.
+ *
+ * 2. SECRET-FREE. A rendered reason carries a fixed CATEGORY and a fixed COMMAND
+ *    FAMILY and nothing else — never the command string, an argument, a branch
+ *    name, a worktree path, an environment value, or exception text. This text
+ *    travels to the worker and into logs, so the bound is enforced at the renderer
+ *    rather than trusted at each call site (the same discipline as
+ *    `permissions.ts`'s `excludeWarning`).
+ *
+ * 3. FAIL-OPEN ON A MALFORMED PAYLOAD, FAIL-CLOSED ON AN AMBIGUOUS COMMAND. Those
+ *    are different failures and they must not share a posture. A payload this hook
+ *    cannot parse means the HOOK is broken or the CLI changed its wire format —
+ *    the deny layer's established contract for that is fail-open (safety margin
+ *    shrinks, liveness does not), because a hook that blocks every tool call on
+ *    its own bug would wedge every worker on the machine. A COMMAND this hook
+ *    cannot resolve is the opposite: the worker is asking to do something
+ *    destructive in a shape the guard cannot prove safe, and "cannot prove safe"
+ *    is the whole reason the guard exists. Substitution, redirection, a `cd` into
+ *    an unknown directory, arguments arriving from stdin through `xargs` — anything
+ *    that stops a destination, ref, or path from being established inside a
+ *    recognized destructive family — denies.
+ *
+ * PreToolUse hooks fire in EVERY permission mode, bypass included. That is what
+ * makes this guard hold even under the `skip_permissions` revert value, and it is
+ * why the hook is provisioned unconditionally rather than only as the
+ * settings-deny fallback.
+ */
+import path from "node:path";
+// ---------------------------------------------------------------------------
+// Reason rendering
+// ---------------------------------------------------------------------------
+/** The stable prefix every denial line carries, so a log scan can find them. */
+export const WORKER_GUARD_REASON_PREFIX = "bridge worker guard";
+/** The single fail-open line emitted for a payload the hook could not read. */
+export const WORKER_GUARD_MALFORMED_LINE = `${WORKER_GUARD_REASON_PREFIX}: payload could not be read; continuing fail-open`;
+/**
+ * Render the one line a denial emits.
+ *
+ * The output is a pure function of two CLOSED vocabularies plus fixed prose. There
+ * is deliberately no parameter through which a command, an argument, a path, a
+ * branch, or an exception could reach this string — the bound is structural rather
+ * than a rule a caller is asked to remember.
+ */
+export function renderWorkerGuardReason(category, family) {
+    return (`${WORKER_GUARD_REASON_PREFIX}: denied ${family} (${category}). ` +
+        "This command family is restricted to the worker's own branch, worktree, and " +
+        "read-only network access. Use a different approach and continue.");
+}
+/** Characters whose presence UNQUOTED means the argv is not the whole story. */
+const UNSAFE_UNQUOTED = new Set(["$", "`", ">", "<"]);
+/** Unquoted separators that end one simple command and begin another. */
+const SEPARATORS = new Set([";", "|", "&"]);
+/**
+ * Split a shell command string into simple commands, honoring ordinary quoting
+ * and backslash escaping.
+ *
+ * This is a LEXER, not a shell: it never executes, expands, globs, or resolves
+ * anything. `mcp_server` carries no shell-parser dependency (`@modelcontextprotocol/sdk`,
+ * `pixelmatch`, `pngjs`, `zod`), and adding one to a security boundary that must
+ * be auditable in one file would be the wrong trade — so this stays private and
+ * narrowly scoped to the families the guard governs.
+ *
+ * Anything it cannot model faithfully sets `unsafe` on the segment rather than
+ * being silently dropped. Under-reporting a segment's risk is the only failure
+ * mode that matters here; over-reporting merely denies a command the worker can
+ * rephrase.
+ */
+export function tokenizeShellCommand(command) {
+    const commands = [];
+    let argv = [];
+    let current = "";
+    let hasCurrent = false;
+    let unsafe = false;
+    const endToken = () => {
+        if (hasCurrent) {
+            argv.push(current);
+            current = "";
+            hasCurrent = false;
+        }
+    };
+    const endCommand = () => {
+        endToken();
+        if (argv.length > 0 || unsafe)
+            commands.push({ argv, unsafe });
+        argv = [];
+        unsafe = false;
+    };
+    for (let i = 0; i < command.length; i += 1) {
+        const ch = command[i];
+        if (ch === "\\") {
+            // A backslash escapes the next character, which is then literal.
+            const next = command[i + 1];
+            if (next !== undefined) {
+                current += next;
+                hasCurrent = true;
+                i += 1;
+            }
+            continue;
+        }
+        if (ch === "'") {
+            // Single quotes are fully literal — nothing inside expands.
+            const close = command.indexOf("'", i + 1);
+            if (close === -1) {
+                // Unterminated quote: the rest of the string is not modelable.
+                unsafe = true;
+                current += command.slice(i + 1);
+                hasCurrent = true;
+                break;
+            }
+            current += command.slice(i + 1, close);
+            hasCurrent = true;
+            i = close;
+            continue;
+        }
+        if (ch === '"') {
+            // Double quotes are literal EXCEPT for expansion, which we cannot evaluate.
+            let j = i + 1;
+            let body = "";
+            let closed = false;
+            while (j < command.length) {
+                const c = command[j];
+                if (c === "\\" && j + 1 < command.length) {
+                    body += command[j + 1];
+                    j += 2;
+                    continue;
+                }
+                if (c === '"') {
+                    closed = true;
+                    break;
+                }
+                if (c === "$" || c === "`")
+                    unsafe = true;
+                body += c;
+                j += 1;
+            }
+            if (!closed)
+                unsafe = true;
+            current += body;
+            hasCurrent = true;
+            i = j;
+            continue;
+        }
+        if (UNSAFE_UNQUOTED.has(ch)) {
+            // Substitution or redirection: the argv we can see is not what will run.
+            unsafe = true;
+            current += ch;
+            hasCurrent = true;
+            continue;
+        }
+        if (SEPARATORS.has(ch)) {
+            endCommand();
+            continue;
+        }
+        if (ch === "\n") {
+            endCommand();
+            continue;
+        }
+        if (ch === " " || ch === "\t" || ch === "\r") {
+            endToken();
+            continue;
+        }
+        current += ch;
+        hasCurrent = true;
+    }
+    endCommand();
+    return commands;
+}
+// ---------------------------------------------------------------------------
+// Payload shape
+// ---------------------------------------------------------------------------
+/** The largest payload the hook will attempt to read, in bytes. */
+export const WORKER_GUARD_MAX_PAYLOAD_BYTES = 1_000_000;
+function asRecord(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+// ---------------------------------------------------------------------------
+// Path containment
+// ---------------------------------------------------------------------------
+/**
+ * Is `candidate` the worktree root or strictly inside it?
+ *
+ * Uses `path.relative` on two RESOLVED absolute paths rather than a string prefix.
+ * A prefix test says `/repo/worktree-evil` is inside `/repo/worktree`, which is
+ * precisely the sibling-directory escape a containment check exists to catch.
+ */
+function isInside(root, candidate) {
+    const rel = path.relative(root, candidate);
+    if (rel === "")
+        return true;
+    if (rel.startsWith(".."))
+        return false;
+    return !path.isAbsolute(rel);
+}
+/**
+ * The directory a command's relative paths resolve against, or `undefined` when
+ * that cannot be established inside the trusted worktree.
+ *
+ * A payload `cwd` that is already outside the worktree is rejected rather than
+ * trusted: every containment answer downstream would otherwise be measured from a
+ * place the worker was not supposed to be standing.
+ */
+function resolveEffectiveCwd(ctx, payloadCwd) {
+    const root = ctx.worktreePath;
+    if (typeof root !== "string" || !path.isAbsolute(root))
+        return undefined;
+    const normalizedRoot = path.resolve(root);
+    if (payloadCwd === undefined)
+        return normalizedRoot;
+    if (typeof payloadCwd !== "string" || payloadCwd.length === 0)
+        return undefined;
+    const resolved = path.isAbsolute(payloadCwd)
+        ? path.resolve(payloadCwd)
+        : path.resolve(normalizedRoot, payloadCwd);
+    return isInside(normalizedRoot, resolved) ? resolved : undefined;
+}
+/** Does every supplied target resolve inside the worktree? */
+function allTargetsContained(ctx, cwd, targets) {
+    const root = ctx.worktreePath;
+    if (typeof root !== "string" || !path.isAbsolute(root))
+        return false;
+    if (cwd === undefined)
+        return false;
+    const normalizedRoot = path.resolve(root);
+    // A home-relative target never resolves against the worktree; treat `~` as
+    // unprovable rather than joining it as a literal directory name.
+    return targets.every((target) => {
+        if (target.length === 0)
+            return false;
+        if (target === "~" || target.startsWith("~/"))
+            return false;
+        const resolved = path.isAbsolute(target)
+            ? path.resolve(target)
+            : path.resolve(cwd, target);
+        return isInside(normalizedRoot, resolved);
+    });
+}
+// ---------------------------------------------------------------------------
+// git
+// ---------------------------------------------------------------------------
+/**
+ * Strip `git`'s own pre-subcommand options and return `{ subcommand, args, cwd }`.
+ *
+ * `git -C <dir>` moves the effective directory before the subcommand runs, so it
+ * is resolved here rather than in each subcommand evaluator — a `git -C .. clean
+ * -fd` that ignored it would be checked against the wrong root.
+ */
+function parseGitInvocation(argv, baseCwd) {
+    let cwd = baseCwd;
+    let unsafe = false;
+    let i = 1;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (token === "-C") {
+            const dir = argv[i + 1];
+            if (dir === undefined || cwd === undefined) {
+                unsafe = true;
+                cwd = undefined;
+            }
+            else {
+                cwd = path.isAbsolute(dir) ? path.resolve(dir) : path.resolve(cwd, dir);
+            }
+            i += 2;
+            continue;
+        }
+        if (token === "-c" || token === "--namespace" || token === "--git-dir" || token === "--work-tree") {
+            // Any of these can change what the next argument means; the safe reading is
+            // that the invocation is no longer one this guard can model.
+            unsafe = true;
+            i += 2;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            i += 1;
+            continue;
+        }
+        break;
+    }
+    return { subcommand: argv[i] ?? "", args: argv.slice(i + 1), cwd, unsafe };
+}
+/** The ref spellings a push to the worker's own branch may legitimately use. */
+function isOwnBranchDestination(destination, workerBranch) {
+    // A refspec `<src>:<dst>` is judged by its DESTINATION half. An empty
+    // destination is a deletion and never matches.
+    const colon = destination.indexOf(":");
+    const dst = colon === -1 ? destination : destination.slice(colon + 1);
+    if (dst.length === 0)
+        return false;
+    const bare = dst.startsWith("+") ? dst.slice(1) : dst;
+    return bare === workerBranch || bare === `refs/heads/${workerBranch}`;
+}
+/**
+ * `git push` — allowed ONLY when every explicit destination is the worker's own
+ * branch.
+ *
+ * A push with no explicit destination at all is allowed: it follows the branch's
+ * configured upstream, which for a conductor worker is the branch it is standing
+ * on. Everything else — a tag, a deletion refspec, another branch, a destination
+ * that cannot be resolved because the branch identity is missing — denies. The
+ * per-flag globs in `permissions.ts` (`--tags`, `--delete`, `refs/tags/`, ` main`,
+ * `epic/`) cover the common spellings; this is the general rule underneath them.
+ */
+function evaluateGitPush(args, ctx) {
+    const deny = { kind: "deny", category: "git-push", family: "git" };
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--") {
+            positional.push(...args.slice(i + 1));
+            break;
+        }
+        if (token.startsWith("-")) {
+            // Any flag naming a destination-shaped value, or altering what a
+            // destination means, is beyond what this guard models safely.
+            if (token === "--tags" ||
+                token === "--delete" ||
+                token === "-d" ||
+                token === "--mirror" ||
+                token === "--all" ||
+                token === "--follow-tags" ||
+                token.startsWith("--repo")) {
+                return deny;
+            }
+            // `-o`/`--push-option`, `--receive-pack`, etc. take a value; skipping only
+            // the flag would misread that value as a destination.
+            if (token === "-o" || token === "--push-option" || token === "--receive-pack" || token === "--exec") {
+                i += 1;
+            }
+            continue;
+        }
+        positional.push(token);
+    }
+    // `git push` / `git push <remote>` with no refspec: the configured upstream.
+    if (positional.length <= 1)
+        return { kind: "allow" };
+    const workerBranch = ctx.workerBranch;
+    if (typeof workerBranch !== "string" || workerBranch.length === 0)
+        return deny;
+    const destinations = positional.slice(1);
+    return destinations.every((d) => isOwnBranchDestination(d, workerBranch))
+        ? { kind: "allow" }
+        : deny;
+}
+/**
+ * `git reset --hard` — allowed against the job branch, `origin/<job branch>`, or
+ * no ref at all (which resets to `HEAD`, discarding only uncommitted work inside
+ * the worktree). Every other explicit ref, and every ref that cannot be checked
+ * because the branch identity is missing, denies.
+ *
+ * A `git reset` WITHOUT `--hard` is not governed here: it moves the index, not the
+ * working tree, and is part of ordinary worker rework.
+ */
+function evaluateGitReset(args, ctx) {
+    const deny = {
+        kind: "deny",
+        category: "git-reset-hard",
+        family: "git",
+    };
+    if (!args.includes("--hard"))
+        return { kind: "allow" };
+    const positional = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--") {
+            positional.push(...args.slice(i + 1));
+            break;
+        }
+        if (token.startsWith("-"))
+            continue;
+        positional.push(token);
+    }
+    if (positional.length === 0)
+        return { kind: "allow" };
+    const workerBranch = ctx.workerBranch;
+    if (typeof workerBranch !== "string" || workerBranch.length === 0)
+        return deny;
+    const allowed = new Set([
+        workerBranch,
+        `origin/${workerBranch}`,
+        `refs/heads/${workerBranch}`,
+        `refs/remotes/origin/${workerBranch}`,
+    ]);
+    return positional.every((ref) => allowed.has(ref)) ? { kind: "allow" } : deny;
+}
+/** `git clean` — its effective directory and every pathspec must be inside. */
+function evaluateGitClean(args, ctx, cwd) {
+    const deny = {
+        kind: "deny",
+        category: "filesystem-clean",
+        family: "git",
+    };
+    if (cwd === undefined)
+        return deny;
+    if (!allTargetsContained(ctx, cwd, [cwd]))
+        return deny;
+    const pathspecs = [];
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        if (token === "--") {
+            pathspecs.push(...args.slice(i + 1));
+            break;
+        }
+        if (token === "-e" || token === "--exclude") {
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("-"))
+            continue;
+        pathspecs.push(token);
+    }
+    if (pathspecs.length === 0)
+        return { kind: "allow" };
+    return allTargetsContained(ctx, cwd, pathspecs) ? { kind: "allow" } : deny;
+}
+// ---------------------------------------------------------------------------
+// rm
+// ---------------------------------------------------------------------------
+/** Do these `rm` options request a recursive, forced delete? */
+function isRecursiveForcedRemove(args) {
+    let recursive = false;
+    let force = false;
+    for (const token of args) {
+        if (token === "--")
+            break;
+        if (token === "--recursive")
+            recursive = true;
+        else if (token === "--force")
+            force = true;
+        else if (token.startsWith("--"))
+            continue;
+        else if (token.startsWith("-") && token.length > 1) {
+            // Combined short options: `-rf`, `-fr`, `-Rf`, and the separated forms.
+            for (const flag of token.slice(1)) {
+                if (flag === "r" || flag === "R")
+                    recursive = true;
+                if (flag === "f")
+                    force = true;
+            }
+        }
+    }
+    return recursive && force;
+}
+/**
+ * `rm -rf` — every target must resolve inside the worktree.
+ *
+ * The two `Bash(rm:*-rf …)` globs in `permissions.ts` already cover `/` and `~`.
+ * This is the case they structurally cannot cover: a RELATIVE target such as
+ * `../../shared` that only becomes an escape once resolved against a cwd.
+ */
+function evaluateRemove(argv, ctx, cwd) {
+    const deny = {
+        kind: "deny",
+        category: "filesystem-remove",
+        family: "rm",
+    };
+    const args = argv.slice(1);
+    if (!isRecursiveForcedRemove(args))
+        return { kind: "allow" };
+    const targets = [];
+    let sawDoubleDash = false;
+    for (const token of args) {
+        if (!sawDoubleDash && token === "--") {
+            sawDoubleDash = true;
+            continue;
+        }
+        if (!sawDoubleDash && token.startsWith("-") && token.length > 1)
+            continue;
+        targets.push(token);
+    }
+    // NO explicit target. A bare `rm -rf` typed by hand is a usage error, but the
+    // shapes that reach here in practice are the ones whose targets come from
+    // somewhere this guard cannot see. There is nothing to check containment
+    // against, so it cannot be proven safe.
+    if (targets.length === 0)
+        return deny;
+    return allTargetsContained(ctx, cwd, targets) ? { kind: "allow" } : deny;
+}
+// ---------------------------------------------------------------------------
+// database
+// ---------------------------------------------------------------------------
+/** `psql` and the `pg_*` family (`pg_dump`, `pg_restore`, `pg_ctl`, …). */
+function isDatabaseCommand(executable) {
+    const base = path.basename(executable);
+    return base === "psql" || base.startsWith("pg_");
+}
+/**
+ * Deny a database command whose arguments mention `DROP` or `TRUNCATE`.
+ *
+ * Matched case-insensitively on WORD boundaries, so an identifier that merely
+ * CONTAINS the letters (`dropbox_sync`, `truncated_log`) is not caught while a
+ * real statement is. The match is deliberately literal: it catches the keyword a
+ * worker TYPED, not every path that could eventually drop something. `pg_restore
+ * --clean` emits `DROP` statements of its own and is NOT caught here — its
+ * arguments never say so — which is why this rule COMPLEMENTS the sentinel
+ * database environment (BAPI-1019, a worker resolves a database that exists
+ * nowhere) rather than standing alone. The keyword is never echoed; only the fixed
+ * category travels.
+ */
+const DESTRUCTIVE_SQL = /\b(?:DROP|TRUNCATE)\b/i;
+function evaluateDatabase(argv) {
+    const deny = {
+        kind: "deny",
+        category: "database-destructive",
+        family: "psql",
+    };
+    return argv.slice(1).some((arg) => DESTRUCTIVE_SQL.test(arg)) ? deny : { kind: "allow" };
+}
+// ---------------------------------------------------------------------------
+// network
+// ---------------------------------------------------------------------------
+const MUTATING_METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
+/**
+ * Deny `curl` / `wget` that carry a mutating verb or a request body.
+ *
+ * Both the separated (`-X DELETE`, `--method=DELETE`) and joined (`-XDELETE`)
+ * spellings are recognized, along with the data-bearing options each tool
+ * establishes (`--data`, `--data-raw`, `-d`, `--form`, `--upload-file`,
+ * `--post-data`, `--body-data`, …). A read-only fetch is untouched: a worker
+ * legitimately reads documentation and package metadata.
+ */
+function evaluateNetwork(argv) {
+    const deny = {
+        kind: "deny",
+        category: "network-mutating",
+        family: "curl",
+    };
+    const base = path.basename(argv[0] ?? "");
+    const args = argv.slice(1);
+    for (let i = 0; i < args.length; i += 1) {
+        const token = args[i];
+        // Method, separated: `-X DELETE`, `--request DELETE`, `--method DELETE`.
+        if (token === "-X" || token === "--request" || token === "--method") {
+            const value = args[i + 1];
+            if (value === undefined)
+                return deny;
+            if (MUTATING_METHODS.has(value.toUpperCase()))
+                return deny;
+            i += 1;
+            continue;
+        }
+        // Method, joined: `-XDELETE`, `--request=DELETE`, `--method=DELETE`.
+        if (token.startsWith("-X") && token.length > 2) {
+            if (MUTATING_METHODS.has(token.slice(2).toUpperCase()))
+                return deny;
+            continue;
+        }
+        if (token.startsWith("--request=") || token.startsWith("--method=")) {
+            const value = token.slice(token.indexOf("=") + 1);
+            if (MUTATING_METHODS.has(value.toUpperCase()))
+                return deny;
+            continue;
+        }
+        // Body-bearing options. `-d` is a body for curl; for wget it is `--post-data`
+        // / `--body-data` / `--body-file`, and `-d` means `--debug`, so the short form
+        // is only treated as a body for curl.
+        if (token === "--data" || token.startsWith("--data=") || token.startsWith("--data-"))
+            return deny;
+        if (token === "--form" || token === "-F" || token === "--upload-file" || token === "-T")
+            return deny;
+        if (token === "--post-data" ||
+            token.startsWith("--post-data=") ||
+            token === "--post-file" ||
+            token.startsWith("--post-file=") ||
+            token === "--body-data" ||
+            token.startsWith("--body-data=") ||
+            token === "--body-file" ||
+            token.startsWith("--body-file=")) {
+            return deny;
+        }
+        if (base === "curl" && token === "-d")
+            return deny;
+    }
+    return { kind: "allow" };
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+/** Which governed family does this executable belong to, if any? */
+function classify(executable) {
+    const base = path.basename(executable);
+    if (base === "git")
+        return "git";
+    if (base === "rm")
+        return "rm";
+    if (isDatabaseCommand(base))
+        return "database";
+    if (base === "curl" || base === "wget")
+        return "network";
+    return null;
+}
+/** The category a governed family denies with when its segment is unmodelable. */
+function unsafeSegmentDecision(family) {
+    switch (family) {
+        case "git":
+            return { kind: "deny", category: "git-push", family: "git" };
+        case "rm":
+            return { kind: "deny", category: "filesystem-remove", family: "rm" };
+        case "database":
+            return { kind: "deny", category: "database-destructive", family: "psql" };
+        case "network":
+            return { kind: "deny", category: "network-mutating", family: "curl" };
+    }
+}
+/**
+ * Transparent prefixes that run another command without changing what it does.
+ *
+ * Without unwrapping, `sudo gh pr merge` and `env FOO=1 rm -rf /` would classify as
+ * `sudo` and `env` — families this guard does not govern — and sail through. The
+ * static deny globs cannot catch them either: they are prefix-shaped
+ * (`Bash(gh:*)`), so a wrapper defeats them too. This is the layer that closes it.
+ */
+const TRANSPARENT_PREFIXES = new Set([
+    "sudo",
+    "env",
+    "command",
+    "nohup",
+    "time",
+    "nice",
+    // `exec` REPLACES the shell with the command that follows it, so what runs is
+    // exactly the remainder — the same relationship `sudo` has to its argument.
+    "exec",
+]);
+/**
+ * Commands that build their argument list from STDIN, so the argv here is not the
+ * whole story.
+ *
+ * `xargs` was originally in {@link TRANSPARENT_PREFIXES}, and that was wrong: a
+ * transparent prefix runs its remainder UNCHANGED, while `xargs` appends arguments
+ * nobody can see at evaluation time. `find / -name x | xargs rm -rf` has no explicit
+ * target at all, so the containment check had nothing to reject and allowed the most
+ * common bulk-delete idiom there is. A governed family behind one of these is
+ * therefore denied outright: its targets cannot be established, and "cannot be
+ * proven safe" is the fail-CLOSED half of this module's contract.
+ */
+const STDIN_ARGUMENT_PREFIXES = new Set(["xargs"]);
+/** Shells whose `-c <string>` argument is itself a command to evaluate. */
+const SHELL_EXECUTABLES = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+/**
+ * Builtins whose ARGUMENTS are re-parsed as a command.
+ *
+ * `eval rm -rf /` joins its arguments and runs the result, so without this the
+ * executable is `eval` — a family this guard does not govern — and everything after
+ * it sails through both the guard and the prefix-shaped static deny globs.
+ */
+const EVAL_BUILTINS = new Set(["eval"]);
+/**
+ * Strip transparent prefixes and their own options, returning the real argv.
+ *
+ * `env`'s `KEY=VALUE` assignments are skipped too — they precede the command and
+ * are not the command. Returns an empty argv when nothing but wrappers remain,
+ * which the caller treats as "nothing governed here".
+ */
+function unwrapTransparentPrefixes(argv) {
+    let rest = argv;
+    // Bounded rather than `while (true)`: a pathological `sudo sudo sudo …` chain
+    // must not spin, and no legitimate command nests wrappers this deep.
+    for (let depth = 0; depth < 8; depth += 1) {
+        const head = rest[0];
+        if (head === undefined)
+            return rest;
+        if (!TRANSPARENT_PREFIXES.has(path.basename(head)))
+            return rest;
+        let i = 1;
+        while (i < rest.length) {
+            const token = rest[i];
+            // `env FOO=1 cmd` — assignments precede the real command.
+            if (path.basename(head) === "env" && /^[A-Za-z_][A-Za-z0-9_]*=/.test(token)) {
+                i += 1;
+                continue;
+            }
+            if (token.startsWith("-")) {
+                i += 1;
+                continue;
+            }
+            break;
+        }
+        rest = rest.slice(i);
+    }
+    return rest;
+}
+/**
+ * Strip `xargs`'s own options and return the command it will run.
+ *
+ * Several of them take a VALUE (`-I {}`, `-n 1`, `-P 4`, `-d ,`, `-s 1024`,
+ * `-E eof`, `-a file`), and skipping only the flag would misread that value as the
+ * command — reading `1` as the executable for `xargs -n 1 rm -rf`. Long forms are
+ * handled in both the `--opt value` and `--opt=value` spellings.
+ */
+function stripStdinPrefixOptions(argv) {
+    const VALUE_OPTS = new Set([
+        "-I",
+        "-i",
+        "-L",
+        "-n",
+        "-P",
+        "-s",
+        "-d",
+        "-E",
+        "-e",
+        "-a",
+        "--replace",
+        "--max-lines",
+        "--max-args",
+        "--max-procs",
+        "--max-chars",
+        "--delimiter",
+        "--eof",
+        "--arg-file",
+    ]);
+    let i = 1;
+    while (i < argv.length) {
+        const token = argv[i];
+        if (token === "--") {
+            i += 1;
+            break;
+        }
+        if (!token.startsWith("-"))
+            break;
+        // `--opt=value` carries its value inline; `--opt value` consumes the next token.
+        if (token.includes("=")) {
+            i += 1;
+            continue;
+        }
+        i += VALUE_OPTS.has(token) ? 2 : 1;
+    }
+    return argv.slice(i);
+}
+/** Evaluate one already-tokenized simple command. */
+function evaluateSimpleCommand(segment, ctx, payloadCwd, depth = 0, stdinFed = false) {
+    const argv = unwrapTransparentPrefixes(segment.argv);
+    const executable = argv[0];
+    if (executable === undefined)
+        return { kind: "allow" };
+    // `sh -c "<command>"` — the real command is an ARGUMENT. Evaluate it rather than
+    // classifying the shell, which governs nothing. Bounded recursion: a nested
+    // `sh -c "sh -c ..."` must terminate, and a chain this deep is not something a
+    // worker writes by accident.
+    if (SHELL_EXECUTABLES.has(path.basename(executable)) && depth < 4) {
+        const cIndex = argv.findIndex((t) => t === "-c");
+        const inner = cIndex === -1 ? undefined : argv[cIndex + 1];
+        if (inner !== undefined) {
+            for (const nested of tokenizeShellCommand(inner)) {
+                const decision = evaluateSimpleCommand(nested, ctx, payloadCwd, depth + 1, stdinFed);
+                if (decision.kind === "deny")
+                    return decision;
+            }
+            return { kind: "allow" };
+        }
+    }
+    // `eval <words>` — join and re-tokenize, exactly as the shell would.
+    if (EVAL_BUILTINS.has(path.basename(executable)) && depth < 4) {
+        for (const nested of tokenizeShellCommand(argv.slice(1).join(" "))) {
+            const decision = evaluateSimpleCommand(nested, ctx, payloadCwd, depth + 1, stdinFed);
+            if (decision.kind === "deny")
+                return decision;
+        }
+        return { kind: "allow" };
+    }
+    // `xargs <command>` — the real argument list arrives on stdin. The REMAINDER is
+    // re-entered through this same function rather than classified directly, so it
+    // gets the identical unwrap-and-recurse treatment: `xargs sudo rm -rf`,
+    // `xargs sh -c '…'`, and `xargs eval '…'` must all resolve to the family they
+    // actually run. Classifying only the literal next token is what let every one of
+    // those through — the same bug the wrapper handling above exists to close, left
+    // open for the composed case.
+    if (STDIN_ARGUMENT_PREFIXES.has(path.basename(executable)) && depth < 4) {
+        const rest = stripStdinPrefixOptions(argv);
+        if (rest.length === 0)
+            return { kind: "allow" };
+        // `stdinFed` from here down: once arguments come from stdin, no containment or
+        // destination question about them can be answered, so reaching a governed
+        // family at any depth below denies.
+        return evaluateSimpleCommand({ argv: rest, unsafe: segment.unsafe }, ctx, payloadCwd, depth + 1, true);
+    }
+    segment = { argv, unsafe: segment.unsafe };
+    const family = classify(executable);
+    if (family === null)
+        return { kind: "allow" };
+    // Arguments supplied from stdin are invisible here, so a governed family reached
+    // under `stdinFed` can never be proven safe regardless of how its visible argv
+    // looks — the fail-CLOSED rule, applied after every wrapper has been resolved.
+    if (stdinFed)
+        return unsafeSegmentDecision(family);
+    // A governed family inside a segment carrying substitution or redirection can
+    // never be proven safe — deny, per the fail-CLOSED half of the contract.
+    if (segment.unsafe)
+        return unsafeSegmentDecision(family);
+    const cwd = resolveEffectiveCwd(ctx, payloadCwd);
+    if (family === "rm")
+        return evaluateRemove(segment.argv, ctx, cwd);
+    if (family === "database")
+        return evaluateDatabase(segment.argv);
+    if (family === "network")
+        return evaluateNetwork(segment.argv);
+    const git = parseGitInvocation(segment.argv, cwd);
+    if (git.subcommand === "push") {
+        return git.unsafe
+            ? { kind: "deny", category: "git-push", family: "git" }
+            : evaluateGitPush(git.args, ctx);
+    }
+    if (git.subcommand === "reset") {
+        return git.unsafe
+            ? { kind: "deny", category: "git-reset-hard", family: "git" }
+            : evaluateGitReset(git.args, ctx);
+    }
+    if (git.subcommand === "clean") {
+        return git.unsafe
+            ? { kind: "deny", category: "filesystem-clean", family: "git" }
+            : evaluateGitClean(git.args, ctx, git.cwd);
+    }
+    return { kind: "allow" };
+}
+/**
+ * Evaluate a parsed PreToolUse payload.
+ *
+ * Accepts `unknown` and validates the shape itself rather than trusting a caller's
+ * cast: this is the boundary where an unexpected CLI wire format shows up, and a
+ * coerced `String(undefined)` command would evaluate the literal text
+ * `"undefined"` as if it were a command and allow it.
+ *
+ * A payload naming a tool other than `Bash` is ALLOWED, not malformed — the hook is
+ * registered under the broad `*` matcher and sees every tool call; only `Bash` is
+ * governed here.
+ */
+export function evaluateWorkerGuardPayload(payload, ctx) {
+    const root = asRecord(payload);
+    if (root === undefined)
+        return { kind: "malformed" };
+    const toolName = root.tool_name ?? root.toolName;
+    if (typeof toolName !== "string")
+        return { kind: "malformed" };
+    if (toolName !== "Bash")
+        return { kind: "allow" };
+    const input = asRecord(root.tool_input ?? root.toolInput);
+    if (input === undefined)
+        return { kind: "malformed" };
+    const command = input.command;
+    if (typeof command !== "string")
+        return { kind: "malformed" };
+    const rawCwd = root.cwd ?? input.cwd;
+    const payloadCwd = typeof rawCwd === "string" ? rawCwd : undefined;
+    for (const segment of tokenizeShellCommand(command)) {
+        const decision = evaluateSimpleCommand(segment, ctx, payloadCwd);
+        if (decision.kind === "deny")
+            return decision;
+    }
+    return { kind: "allow" };
+}
+/**
+ * Parse raw stdin text and evaluate it — the whole hook decision in one call.
+ *
+ * An oversized or unparseable body is `malformed` (fail-open), never a thrown
+ * exception: the binary's job is to emit one bounded line and get out of the way.
+ */
+export function evaluateWorkerGuardInput(raw, ctx) {
+    if (typeof raw !== "string")
+        return { kind: "malformed" };
+    if (raw.length > WORKER_GUARD_MAX_PAYLOAD_BYTES)
+        return { kind: "malformed" };
+    if (raw.trim().length === 0)
+        return { kind: "malformed" };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { kind: "malformed" };
+    }
+    try {
+        return evaluateWorkerGuardPayload(parsed, ctx);
+    }
+    catch {
+        // Defensive: an unexpected evaluator failure is a HOOK problem, not a worker
+        // problem, so it takes the fail-open path rather than blocking the tool loop.
+        return { kind: "malformed" };
+    }
+}
+/** The flag through which provisioning templates the trusted worktree root. */
+export const WORKER_GUARD_ROOT_FLAG = "--worktree-root";
+/**
+ * Read the guard's trusted context.
+ *
+ * The worktree root comes from `--worktree-root <abs path>`, templated into the
+ * provisioned hook command by `provisionExecutorDenyLayer`, which already HOLDS
+ * the trusted value as its first parameter. It is deliberately not inferred from
+ * the hook process's `cwd`: nothing in the PreToolUse contract guarantees the hook
+ * runs from the project root, and a containment check measured from the wrong root
+ * is worse than no containment check, because it reports success. The hook's own
+ * `cwd` remains a LAST-RESORT fallback for a worktree provisioned by an older
+ * executor build whose settings file carries no flag.
+ *
+ * The branch comes from `BAPI_WORKER_BRANCH`, which the executor injects from the
+ * prepared worktree and denies from `parentEnv` so an operator's ambient value
+ * cannot redefine what the guard treats as safe.
+ */
+export function resolveWorkerGuardContext(env, cwd, argv = []) {
+    const ctx = {};
+    let root;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] === WORKER_GUARD_ROOT_FLAG) {
+            root = argv[i + 1];
+            break;
+        }
+        if (argv[i].startsWith(`${WORKER_GUARD_ROOT_FLAG}=`)) {
+            root = argv[i].slice(WORKER_GUARD_ROOT_FLAG.length + 1);
+            break;
+        }
+    }
+    if (root === undefined && typeof cwd === "string")
+        root = cwd;
+    if (typeof root === "string" && path.isAbsolute(root))
+        ctx.worktreePath = path.resolve(root);
+    const branch = env.BAPI_WORKER_BRANCH;
+    if (typeof branch === "string" && branch.trim().length > 0)
+        ctx.workerBranch = branch.trim();
+    return ctx;
+}