deepdebug-local-agent 1.0.23 → 1.2.0

package/src/utils/exec-policy.js

@@ -0,0 +1,962 @@
+/**
+ * exec-policy.js — ALLOWLIST for shell execution (replaces the substring blocklist).
+ *
+ * A command is accepted only when every segment of it (split on && || ; | and
+ * newlines) belongs to a declared command family and its arguments validate:
+ *
+ *   git-read     read-only git: status, log, diff, show, rev-parse, ls-files,
+ *                blame, grep, branch/tag/remote listing, config --get, fetch …
+ *   pkg          package-manager install / test / build / lint for an ecosystem
+ *                DETECTED in the workspace (npm/yarn/pnpm, mvn/mvnw, gradle/
+ *                gradlew, pip/poetry/uv, go, cargo, dotnet)
+ *   test         test runners (jest, vitest, mocha, pytest, node --test, …)
+ *   lint         linters / formatters / type checkers (eslint, prettier, tsc, …)
+ *   file-read    cat, head, tail, ls, find (no -exec/-delete), grep/rg, wc, …
+ *   file-write   mkdir, touch, cp, mv, rm, tee, redirections — inside the root
+ *   nav          cd <dir inside the workspace root>
+ *
+ * Shell features that turn data into code are refused outright: $VAR / $( ) /
+ * backticks, subshells and grouping, background &, process substitution,
+ * here-docs, leading ~ and comments. Every path-like argument (absolute, `..`,
+ * `~`) must resolve inside the workspace root (sandbox.js).
+ *
+ * Anything else is rejected with a reason — unless the request carries a human
+ * approval token issued by PolicyGate (REQUIRE_HUMAN) for exactly that command
+ * (approval-token.js), or it is a signed platform-authored tool command.
+ *
+ * Mode (LOCAL_AGENT_EXEC_POLICY_MODE): off | warn | enforce (default since the
+ * 2026-10-11 security review; before, warn let every non-allowlisted command run).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { isInsideRoot, confineToRoot } from "./sandbox.js";
+import { resolveMode, logDecision, NonceCache } from "./request-signing.js";
+import { verifyApprovalToken, MAX_APPROVAL_LIFETIME_SECONDS } from "./approval-token.js";
+
+/** Single-use approval jti's, kept for the maximum approval lifetime (+ skew). */
+export const approvalNonces = new NonceCache({ ttlMs: (MAX_APPROVAL_LIFETIME_SECONDS + 120) * 1000, max: 20_000 });
+
+// ─────────────────────────────── tokenizer ───────────────────────────────
+
+/**
+ * Splits a shell command into segments of argv + redirections, refusing
+ * expansion/grouping syntax. Returns { ok, segments } or { ok: false, reason }.
+ */
+export function tokenize(command) {
+    if (typeof command !== "string" || !command.trim()) return { ok: false, reason: "empty command" };
+    if (command.length > 8000) return { ok: false, reason: "command too long" };
+    const segments = [];
+    let argv = [];
+    let quoted = [];
+    let redirects = [];
+    let word = "";
+    let inWord = false;
+    let quotedWord = false;
+    let pendingRedirect = null;
+    const fail = (reason) => ({ ok: false, reason });
+
+    const endWord = () => {
+        if (!inWord) return null;
+        if (pendingRedirect) {
+            pendingRedirect.target = word;
+            redirects.push(pendingRedirect);
+            pendingRedirect = null;
+        } else {
+            argv.push(word);
+            quoted.push(quotedWord);
+        }
+        word = ""; inWord = false; quotedWord = false;
+        return null;
+    };
+    const endSegment = (sep) => {
+        endWord();
+        if (pendingRedirect) return fail("redirection without a target");
+        if (argv.length === 0) return fail(sep ? `empty command before '${sep}'` : "empty command");
+        segments.push({ argv, quoted, redirects, sep: sep || null });
+        argv = []; quoted = []; redirects = [];
+        return null;
+    };
+
+    for (let i = 0; i < command.length; i++) {
+        const c = command[i];
+        const n = command[i + 1];
+        if (c === "'") {
+            const j = command.indexOf("'", i + 1);
+            if (j < 0) return fail("unterminated single quote");
+            word += command.slice(i + 1, j); inWord = true; quotedWord = true; i = j; continue;
+        }
+        if (c === '"') {
+            let j = i + 1;
+            let buf = "";
+            for (; j < command.length && command[j] !== '"'; j++) {
+                const d = command[j];
+                if (d === "$" || d === "`") return fail("variable or command expansion is not allowed");
+                if (d === "\\" && (command[j + 1] === '"' || command[j + 1] === "\\")) { buf += command[j + 1]; j++; continue; }
+                buf += d;
+            }
+            if (j >= command.length) return fail("unterminated double quote");
+            word += buf; inWord = true; quotedWord = true; i = j; continue;
+        }
+        if (c === "\\") {
+            if (n === undefined) return fail("trailing backslash");
+            if (n === "\n") { i++; continue; }
+            word += n; inWord = true; i++; continue;
+        }
+        if (c === "$" || c === "`") return fail("variable or command expansion is not allowed");
+        if (c === "(" || c === ")") return fail("subshells and grouping are not allowed");
+        if (!inWord && (c === "{" || c === "}")) return fail("subshells and grouping are not allowed");
+        if (!inWord && (c === "#")) return fail("comments are not allowed");
+        if (!inWord && c === "~") return fail("home-directory (~) paths are not allowed");
+        if (!inWord && c === "!") return fail("history expansion / negation is not allowed");
+        if (c === " " || c === "\t") { endWord(); continue; }
+        if (c === "\n" || c === ";") { const e = endSegment(";"); if (e) return e; continue; }
+        if (c === "&") {
+            if (n === "&") { const e = endSegment("&&"); if (e) return e; i++; continue; }
+            if (n === ">") return fail("'&>' redirection is not allowed");
+            return fail("background execution (&) is not allowed");
+        }
+        if (c === "|") {
+            if (n === "|") { const e = endSegment("||"); if (e) return e; i++; continue; }
+            if (n === "&") return fail("'|&' is not allowed");
+            const e = endSegment("|"); if (e) return e; continue;
+        }
+        if (c === ">" || c === "<") {
+            let fd = c === "<" ? "0" : "1";
+            if (inWord && !quotedWord && /^[0-9]$/.test(word)) { fd = word; word = ""; inWord = false; }
+            else endWord();
+            if (pendingRedirect) return fail("redirection without a target");
+            if (c === "<") {
+                if (n === "<") return fail("here-documents are not allowed");
+                if (n === "(") return fail("process substitution is not allowed");
+                pendingRedirect = { fd, op: "<" };
+                continue;
+            }
+            if (n === "(") return fail("process substitution is not allowed");
+            if (n === "&") {
+                const m = command.slice(i + 2).match(/^([0-9])/);
+                if (!m) return fail("invalid fd duplication");
+                redirects.push({ fd, op: ">&", target: m[1] });
+                i += 2; continue;
+            }
+            if (n === ">") { pendingRedirect = { fd, op: ">>" }; i++; continue; }
+            if (n === "|") return fail("'>|' is not allowed");
+            pendingRedirect = { fd, op: ">" };
+            continue;
+        }
+        word += c; inWord = true;
+    }
+    endWord();
+    if (pendingRedirect) return fail("redirection without a target");
+    if (argv.length === 0) {
+        if (segments.length === 0) return fail("empty command");
+        return fail("command ends with an operator");
+    }
+    segments.push({ argv, quoted, redirects, sep: null });
+    return { ok: true, segments };
+}
+
+// ─────────────────────────── ecosystem detection ──────────────────────────
+
+const MARKERS = [
+    ["node", ["package.json"]],
+    ["maven", ["pom.xml", "mvnw"]],
+    ["gradle", ["build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts", "gradlew"]],
+    ["python", ["requirements.txt", "requirements-dev.txt", "pyproject.toml", "setup.py", "setup.cfg", "Pipfile", "tox.ini"]],
+    ["go", ["go.mod"]],
+    ["rust", ["Cargo.toml"]],
+];
+const detectCache = new Map();
+
+/** Ecosystems present in the root or its immediate sub-directories (multi-repo). */
+export function detectEcosystems(root, { now = Date.now() } = {}) {
+    const hit = detectCache.get(root);
+    if (hit && hit.exp > now) return hit.set;
+    const set = new Set();
+    const scan = (dir) => {
+        let names;
+        try { names = fs.readdirSync(dir); } catch { return; }
+        for (const [eco, files] of MARKERS) if (files.some(f => names.includes(f))) set.add(eco);
+        if (names.some(f => /\.(csproj|fsproj|sln)$/.test(f))) set.add("dotnet");
+        return names;
+    };
+    const top = scan(root) || [];
+    for (const name of top) {
+        if (name.startsWith(".") || name === "node_modules") continue;
+        try { if (fs.statSync(path.join(root, name)).isDirectory()) scan(path.join(root, name)); } catch { /* skip */ }
+    }
+    detectCache.set(root, { set, exp: now + 60_000 });
+    if (detectCache.size > 500) detectCache.clear();
+    return set;
+}
+
+// ──────────────────────────────── helpers ────────────────────────────────
+
+const ok = (family) => ({ ok: true, family });
+const no = (reason) => ({ ok: false, reason });
+const isOpt = (a) => a.startsWith("-") && a !== "-";
+
+// Working directories a relative path may be resolved against while one command
+// string is evaluated: the root plus every `cd` / `git -C` target seen so far
+// (a path must be safe against ALL of them). Evaluation is synchronous, so a
+// module-level list is safe.
+let CWDS = null;
+const cwds = (root) => (CWDS && CWDS.length ? CWDS : [root]);
+
+/** Realpath-confined check (symlinks resolved) of `t` against every possible cwd. */
+function inside(root, t) {
+    if (t === "/dev/null") return true;
+    if (typeof t !== "string" || t.startsWith("~")) return false;
+    return cwds(root).every(c => isInsideRoot(root, path.resolve(c, t)));
+}
+
+const GLOB = /[*?[]/;
+
+/**
+ * Every non-flag token (and every --opt=value) that is path-like — absolute,
+ * containing a separator or `..`, or EXISTING on disk relative to a possible
+ * cwd — is realpath-resolved (symlinks followed) and must stay inside the
+ * root. For a glob, the directory part before the first wildcard is checked
+ * (the shell-expanded case is also checked in evaluateCommand).
+ */
+function pathInside(root, token) {
+    if (token === "/dev/null") return true;
+    let t = token;
+    if (t.startsWith("-")) {
+        const eq = t.indexOf("=");
+        if (eq < 0) return true;
+        t = t.slice(eq + 1);
+    }
+    if (!t) return true;
+    if (t.startsWith("~")) return false;
+    if (GLOB.test(t)) {
+        const segs = t.split(/[\\/]/);
+        const i = segs.findIndex(x => GLOB.test(x));
+        const prefix = segs.slice(0, i).join("/") || (path.isAbsolute(t) ? "/" : ".");
+        return inside(root, prefix);
+    }
+    const pathy = path.isAbsolute(t) || /[\\/]/.test(t) || t.split(/[\\/]/).includes("..")
+        || cwds(root).some(c => { try { return fs.existsSync(path.resolve(c, t)); } catch { return false; } });
+    if (!pathy) return true;
+    return inside(root, t);
+}
+
+function checkPaths(root, args, skip = new Set()) {
+    for (let i = 0; i < args.length; i++) {
+        if (skip.has(i)) continue;
+        if (!pathInside(root, args[i])) return no(`path '${args[i]}' is outside the workspace root`);
+    }
+    return null;
+}
+
+/**
+ * An UNQUOTED glob is expanded by the shell before any tool sees it, so its
+ * matches must be safe too: wildcards only in the last segment, and no
+ * symlink in that directory may resolve outside the root.
+ */
+function checkShellGlob(root, t) {
+    const segs = t.split("/");
+    const i = segs.findIndex(x => GLOB.test(x));
+    if (i < 0) return null;
+    if (i !== segs.length - 1) return no(`unquoted glob '${t}' may only use wildcards in its last path segment (quote it to let the tool expand it)`);
+    const dir = segs.slice(0, i).join("/") || (t.startsWith("/") ? "/" : ".");
+    if (!inside(root, dir)) return no(`path '${t}' is outside the workspace root`);
+    for (const c of cwds(root)) {
+        const abs = path.resolve(c, dir);
+        let names = [];
+        try { names = fs.readdirSync(abs); } catch { continue; }
+        for (const n of names) {
+            const full = path.join(abs, n);
+            try { if (fs.lstatSync(full).isSymbolicLink() && !isInsideRoot(root, full)) return no(`glob '${t}' matches symlink '${n}' that points outside the workspace root`); } catch { /* ignore */ }
+        }
+    }
+    return null;
+}
+
+// ── protected paths: writing these can make later builds/tests run attacker code ──
+const PROTECTED_DIRS = new Set([".git", ".husky", ".githooks", ".mvn", ".gradle", ".yarn", ".cargo", ".devcontainer", ".vscode"]);
+const PROTECTED_FILES = new Set([
+    "package.json", "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml", "pnpm-workspace.yaml",
+    ".npmrc", ".yarnrc", ".yarnrc.yml", ".pnpmfile.cjs", "Makefile", "makefile", "GNUmakefile",
+    "pom.xml", "mvnw", "mvnw.cmd", "build.gradle", "build.gradle.kts", "settings.gradle", "settings.gradle.kts",
+    "gradle.properties", "gradlew", "gradlew.bat", "init.gradle", "setup.py", "setup.cfg", "pyproject.toml",
+    "conftest.py", "tox.ini", "noxfile.py", "pytest.ini", "Pipfile", "requirements.txt", "requirements-dev.txt",
+    "Cargo.toml", "build.rs", ".cargo", "Directory.Build.props", "Directory.Build.targets", "global.json",
+    "NuGet.config", "nuget.config", ".pre-commit-config.yaml", ".envrc", ".babelrc", "Dockerfile", "docker-compose.yml",
+    "go.mod", "go.work", "Taskfile.yml", "justfile", "Rakefile", "Gemfile",
+]);
+const PROTECTED_FILE_RE = /^(\.?(jest|vitest|vite|webpack|rollup|babel|eslint|prettier|playwright|cypress|karma|nyc|c8|mocha|ava|tsup|esbuild|stylelint|postcss|tailwind|next|nuxt|svelte|astro)(rc)?(\.config)?(\.[\w-]+)*\.(c|m)?(j|t)sx?|\.(eslintrc|prettierrc|mocharc|babelrc|nycrc|c8rc|lintstagedrc|huskyrc)(\..+)?|.*\.(csproj|fsproj|vbproj|props|targets|gradle|gradle\.kts))$/;
+
+/**
+ * True when `t` (realpath-resolved, symlinks followed) is inside .git/, a hook
+ * dir, or is build/test configuration that executes code. Such files may only
+ * change through the platform's signed apply-patch tool, never through exec.
+ */
+function isProtected(root, t) {
+    let realRoot;
+    try { realRoot = confineToRoot(root, "."); } catch { return true; }
+    return cwds(root).some(c => {
+        let real;
+        try { real = confineToRoot(root, path.resolve(c, t)); } catch { return true; }
+        const rel = path.relative(realRoot, real);
+        if (!rel) return false;
+        const parts = rel.split(path.sep);
+        if (parts.some(x => PROTECTED_DIRS.has(x))) return true;
+        for (let i = 0; i + 1 < parts.length; i++) if (parts[i] === "gradle" && parts[i + 1] === "wrapper") return true;
+        const base = parts[parts.length - 1];
+        return PROTECTED_FILES.has(base) || PROTECTED_FILE_RE.test(base);
+    });
+}
+
+function writeTargetError(root, tool, t) {
+    if (!inside(root, t)) return no(`${tool} target '${t}' is outside the workspace root`);
+    if (isProtected(root, t)) return no(`${tool} may not modify '${t}' (.git/, hooks and build/test configuration can only change through the signed apply-patch tool)`);
+    return null;
+}
+
+const NPM_SCRIPT = /^(test|tests|build|lint|typecheck|type-check|check|compile|format|fmt|prettier|eslint|tsc|verify|coverage|ci)([:._-][\w:.-]+)?$/;
+const REGISTRY_PKG = /^(@[a-z0-9][\w.-]*\/)?[a-z0-9][\w.-]*(@[\w.^~<>=*|-]+)?$/i;
+const PY_PKG = /^[A-Za-z0-9][A-Za-z0-9._-]*(\[[A-Za-z0-9,._-]+\])?([<>=!~]=?[A-Za-z0-9.*+!-]+(,[<>=!~]=?[A-Za-z0-9.*+!-]+)*)?$/;
+const TEST_TOOLS = new Set(["jest", "vitest", "mocha", "ava", "playwright", "cypress", "karma"]);
+/** Coverage tools WRAP another command: that command is validated recursively. */
+const COVERAGE_WRAPPERS = new Set(["c8", "nyc"]);
+const LINT_TOOLS = new Set(["eslint", "prettier", "tsc", "stylelint", "biome", "vue-tsc", "ts-prune", "depcheck"]);
+
+// ───────────────────────────── family: git ─────────────────────────────
+
+const GIT_DANGEROUS_OPT = /^(--output|--ext-diff|--textconv|--upload-pack|--receive-pack|--exec|--config-env|--open-files-in-pager|-O|--template|--run|--git-dir|--work-tree|--namespace|--super-prefix)(=|$)/;
+const GIT_SAFE_CONFIG = /^(core\.quotepath|color\.[\w.]+|core\.abbrev|log\.showsignature|diff\.renames|i18n\.logoutputencoding)=[\w.-]*$/i;
+const GIT_READ = new Set(["status", "log", "diff", "show", "rev-parse", "ls-files", "ls-tree", "blame", "describe",
+    "shortlog", "grep", "cat-file", "for-each-ref", "merge-base", "rev-list", "show-ref", "name-rev", "whatchanged",
+    "diff-tree", "diff-files", "diff-index", "count-objects", "version", "help", "var"]);
+const GIT_BRANCH_WRITE = /^(-d|-D|-m|-M|-c|-C|-f|-u|--delete|--move|--copy|--force|--set-upstream-to|--unset-upstream|--edit-description|--track|--no-track|--create-reflog)(=|$)/;
+const GIT_BRANCH_LIST = /^(-l|--list|--contains|--no-contains|--merged|--no-merged|--points-at|--format|--sort)(=|$)/;
+
+function gitFamily(argv, root) {
+    let i = 1;
+    for (; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "-C") {
+            if (!argv[i + 1] || !inside(root, argv[i + 1])) return no("git -C must point inside the workspace root");
+            CWDS = [...cwds(root), ...cwds(root).map(c => path.resolve(c, argv[i + 1]))];
+            i++; continue;
+        }
+        if (a === "-c") { if (!GIT_SAFE_CONFIG.test(argv[i + 1] || "")) return no(`git -c ${argv[i + 1] || ""} is not allowed`); i++; continue; }
+        if (a === "--no-pager" || a === "--no-optional-locks" || a === "-P") continue;
+        break;
+    }
+    const sub = argv[i];
+    const rest = argv.slice(i + 1);
+    if (!sub) return no("git without a subcommand");
+    for (const a of rest) if (GIT_DANGEROUS_OPT.test(a)) return no(`git option ${a.split("=")[0]} is not allowed`);
+    const pathErr = checkPaths(root, rest, sub === "grep" || sub === "log" ? patternIndexes(rest) : new Set());
+    if (pathErr) return pathErr;
+    if (GIT_READ.has(sub)) return ok("git-read");
+    switch (sub) {
+        case "branch": {
+            if (rest.some(a => GIT_BRANCH_WRITE.test(a))) return no("git branch modification requires approval");
+            const positional = rest.filter(a => !isOpt(a));
+            if (positional.length && !rest.some(a => GIT_BRANCH_LIST.test(a))) return no("creating a branch requires approval");
+            return ok("git-read");
+        }
+        case "tag": {
+            if (rest.some(a => /^(-d|--delete|-f|--force|-a|--annotate|-s|--sign|-m|--message|-F|--file)(=|$)/.test(a))) return no("creating or deleting tags requires approval");
+            const listing = rest.some(a => /^(-l|--list)$/.test(a));
+            if (listing || rest.every(a => isOpt(a))) return ok("git-read");
+            return no("creating tags requires approval");
+        }
+        case "remote":
+            if (rest.length === 0 || (rest.length === 1 && rest[0] === "-v")) return ok("git-read");
+            if ((rest[0] === "get-url" || rest[0] === "show") && rest.length <= 3) return ok("git-read");
+            return no("changing git remotes requires approval");
+        case "config":
+            if (rest.some(a => /^(--get|--get-all|--get-regexp|--list|-l)$/.test(a)) && !rest.some(a => /^(--add|--unset|--unset-all|--replace-all|--edit|-e|--rename-section|--remove-section)$/.test(a)))
+                return ok("git-read");
+            return no("writing git config requires approval");
+        case "stash":
+            if (rest[0] === "list" || rest[0] === "show") return ok("git-read");
+            return no("git stash modification requires approval");
+        case "reflog":
+            if (rest.length === 0 || rest[0] === "show") return ok("git-read");
+            return no("git reflog modification requires approval");
+        case "worktree":
+            if (rest[0] === "list") return ok("git-read");
+            return no("git worktree modification requires approval");
+        case "fetch":
+            if (rest.every(a => /^(--all|--prune|-p|--tags|--no-tags|--quiet|-q|--depth=\d+|--unshallow|--dry-run|--verbose|-v)$/.test(a) || !isOpt(a)))
+                return ok("git-read");
+            return no("git fetch option not allowed");
+        default:
+            return no(`git ${sub} is not a read-only operation (requires approval)`);
+    }
+}
+
+/** For grep-like tools: index of the pattern positional (not a path). */
+function patternIndexes(args) {
+    const skip = new Set();
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === "-e" || args[i] === "--regexp" || args[i] === "-f" || args[i] === "--grep" || args[i] === "--author" || args[i] === "-S" || args[i] === "-G") { skip.add(i + 1); continue; }
+        if (/^--(grep|author|committer|format|pretty|regexp)=/.test(args[i])) { skip.add(i); continue; }
+    }
+    if (![...skip].length) {
+        const first = args.findIndex(a => !isOpt(a));
+        if (first >= 0) skip.add(first);
+    }
+    return skip;
+}
+
+// ─────────────────────────── family: packages ───────────────────────────
+
+function needEco(ecos, eco, tool) {
+    return ecos.has(eco) ? null : no(`${tool} is only allowed in a workspace with a detected ${eco} project`);
+}
+
+/**
+ * Node runtime flags that load or evaluate arbitrary code (or open a debugger),
+ * refused anywhere in a package-manager / test-runner command line — including
+ * after `--`, where npm/yarn/pnpm pass them through to the script.
+ */
+const NODE_RUNTIME_FLAG = /^(--require|-r|--import|--loader|--experimental-loader|--inspect|--inspect-brk|--inspect-port|--inspect-wait|--eval|-e|--print|-p|--experimental-vm-modules|--experimental-policy|--env-file|--node-options|--preserve-symlinks-main)(=|$)/;
+function nodeRuntimeFlag(args) {
+    const bad = args.find(a => NODE_RUNTIME_FLAG.test(a));
+    return bad ? no(`node runtime flag ${bad.split("=")[0]} is not allowed (it loads or evaluates arbitrary code)`) : null;
+}
+
+function npmFamily(argv, root, ecos) {
+    const tool = path.basename(argv[0]);
+    const e = needEco(ecos, "node", tool); if (e) return e;
+    const [sub, ...rest] = argv.slice(1);
+    const dd = rest.indexOf("--");
+    const own = dd >= 0 ? rest.slice(0, dd) : rest;
+    const pathErr = checkPaths(root, rest); if (pathErr) return pathErr;
+    if (own.some(a => /^(--registry|--userconfig|--globalconfig|--prefix|-g|--global|--location=global|--script-shell|--node-options)(=|$)/.test(a)))
+        return no(`${tool} option not allowed`);
+    const namedPkgs = (args) => args.filter(a => !isOpt(a));
+    const rt = nodeRuntimeFlag(rest); if (rt) return rt;
+    const isScript = (s) => NPM_SCRIPT.test(s || "");
+    if (!sub && tool === "yarn") return ok("pkg");
+    switch (sub) {
+        case "ci": case "install": case "i": case "add":
+            // Only lockfile/manifest installs; adding a named package is a new
+            // (unpinned) dependency -> PolicyGate ADD_UNPINNED_DEPENDENCY approval.
+            if (sub === "add" || namedPkgs(own).length) return no(`installing a named package requires approval (ADD_UNPINNED_DEPENDENCY): ${namedPkgs(own).join(" ") || sub}`);
+            return ok("pkg");
+        case "test": case "t": case "build": case "lint":
+            return ok("pkg");
+        case "run": case "run-script":
+            return isScript(own.find(a => !isOpt(a))) ? ok("pkg") : no(`${tool} run: only test/build/lint/typecheck-style scripts are allowed`);
+        case "ls": case "list": case "outdated": case "why": case "-v": case "--version": case "view": case "info":
+            return ok("pkg");
+        case "audit":
+            return own.includes("fix") ? no("npm audit fix requires approval") : ok("pkg");
+        case "exec": case "dlx": {
+            const i = own.findIndex(a => !isOpt(a));
+            const wrapped = i >= 0 ? own.slice(i).concat(dd >= 0 ? rest.slice(dd + 1) : []) : (dd >= 0 ? rest.slice(dd + 1) : []);
+            if (!wrapped.length) return no(`${tool} ${sub} needs a command`);
+            const name = path.basename(wrapped[0]);
+            if (!TEST_TOOLS.has(name) && !LINT_TOOLS.has(name) && !COVERAGE_WRAPPERS.has(name)) return no(`${tool} ${sub}: ${wrapped[0]} is not an allowed test runner or linter`);
+            return evaluateArgv(wrapped, root, ecos, 1);
+        }
+        default:
+            if (tool === "yarn" && isScript(sub)) return ok("pkg");
+            return no(`${tool} ${sub} is not an allowed package-manager operation`);
+    }
+}
+
+/**
+ * npx <tool> …: the tool must itself be an allowed test runner / linter (or
+ * wrapper), and the WHOLE wrapped command is validated recursively.
+ */
+function npxFamily(argv, root, ecos, depth) {
+    const e = needEco(ecos, "node", "npx"); if (e) return e;
+    const rest = argv.slice(1);
+    let i = 0;
+    for (; i < rest.length && isOpt(rest[i]); i++) {
+        if (/^(-p|--package|-c|--call)(=|$)/.test(rest[i])) return no("npx --package/--call is not allowed");
+        if (!/^(--no-install|--no|-y|--yes|--quiet|-q)$/.test(rest[i])) return no(`npx option ${rest[i]} is not allowed`);
+    }
+    if (i >= rest.length) return no("npx needs a command");
+    const wrapped = rest.slice(i);
+    wrapped[0] = wrapped[0].replace(/^(@?[^@]+)@[^/]*$/, "$1");
+    const name = path.basename(wrapped[0]);
+    if (!TEST_TOOLS.has(name) && !LINT_TOOLS.has(name) && !COVERAGE_WRAPPERS.has(name)) return no(`${rest[i]} is not an allowed test runner or linter`);
+    return evaluateArgv(wrapped, root, ecos, depth + 1);
+}
+
+const MVN_GOAL = /^(clean|validate|compile|test-compile|test|package|verify|install|dependency:(tree|resolve|list|analyze|go-offline)|help:effective-pom|checkstyle:check|spotless:(check|apply)|surefire:test|failsafe:integration-test|jacoco:report|versions:display-dependency-updates|pmd:check|spotbugs:check)$/;
+function mavenFamily(argv, root, ecos) {
+    const e = needEco(ecos, "maven", "maven"); if (e) return e;
+    const args = argv.slice(1);
+    const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (/^-D/.test(a)) {
+            const prop = a.slice(2).split("=")[0];
+            if (!/^[\w.-]+$/.test(prop) || /^(exec|maven\.repo\.local|settings|maven\.ext|env\.)/.test(prop)) return no(`maven property ${prop} is not allowed`);
+            continue;
+        }
+        if (/^(-q|--quiet|-B|--batch-mode|-e|--errors|-X|--debug|-o|--offline|-U|--update-snapshots|-am|--also-make|-amd|--also-make-dependents|-ntp|--no-transfer-progress|-fae|-ff|-V|-v|--version)$/.test(a)) continue;
+        if (/^(-T|--threads|-pl|--projects|-P|--activate-profiles|-f|--file|-rf|--resume-from)$/.test(a)) { i++; continue; }
+        if (/^(-s|--settings|-gs|--global-settings|-t|--toolchains)$/.test(a)) return no("custom maven settings are not allowed");
+        if (isOpt(a)) return no(`maven option ${a} is not allowed`);
+        if (!MVN_GOAL.test(a)) return no(`maven goal ${a} is not allowed`);
+    }
+    return ok("pkg");
+}
+
+const GRADLE_TASK = /^(:?[\w.-]+:)*(build|assemble|test|check|clean|compile\w*|classes|testClasses|jar|bootJar|lint\w*|dependencies|dependencyInsight|projects|tasks|properties|spotlessCheck|spotlessApply|ktlintCheck|ktlintFormat|detekt|jacocoTestReport|integrationTest|javadoc)$/;
+function gradleFamily(argv, root, ecos) {
+    const e = needEco(ecos, "gradle", "gradle"); if (e) return e;
+    const args = argv.slice(1);
+    const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (/^(-I|--init-script|-c|--settings-file|-g|--gradle-user-home|--project-cache-dir)(=|$)/.test(a)) return no(`gradle option ${a} is not allowed`);
+        if (/^-[DP]/.test(a)) { if (!/^-[DP][\w.-]+(=[^\s]*)?$/.test(a)) return no(`gradle property ${a} is not allowed`); continue; }
+        if (/^(--tests|-x|--exclude-task|-p|--project-dir|--dependency|--configuration|--console|--max-workers)$/.test(a)) { i++; continue; }
+        if (/^(--no-daemon|--daemon|--offline|-q|--quiet|--info|-i|--debug|-d|--stacktrace|-s|--scan|--no-scan|--build-cache|--no-build-cache|--parallel|--continue|--refresh-dependencies|--warning-mode=\w+|--console=\w+|--max-workers=\d+|--version|-v|--rerun-tasks)$/.test(a)) continue;
+        if (isOpt(a)) return no(`gradle option ${a} is not allowed`);
+        if (!GRADLE_TASK.test(a)) return no(`gradle task ${a} is not allowed`);
+    }
+    return ok("pkg");
+}
+
+function pipArgs(args, root) {
+    const [sub, ...rest] = args;
+    if (rest.some(a => /^(-i|--index-url|--extra-index-url|-f|--find-links|--trusted-host|--target|-t|--prefix|--root|--user|--src|--config-settings|-C)(=|$)/.test(a)))
+        return no("pip index/target options are not allowed");
+    const pathErr = checkPaths(root, rest); if (pathErr) return pathErr;
+    switch (sub) {
+        case "list": case "show": case "freeze": case "check": case "--version": case "-V":
+            return ok("pkg");
+        case "install": {
+            for (let i = 0; i < rest.length; i++) {
+                const a = rest[i];
+                if (a === "-r" || a === "--requirement" || a === "-c" || a === "--constraint") { i++; continue; }
+                if (a === "-e" || a === "--editable") { const t = rest[i + 1]; if (!t || /:\/\//.test(t) || !inside(root, t)) return no("pip install -e must point inside the workspace"); i++; continue; }
+                if (/^(-U|--upgrade|-q|--quiet|--no-deps|--no-cache-dir|--pre|--no-input|--disable-pip-version-check|--break-system-packages|--require-hashes)$/.test(a)) continue;
+                if (isOpt(a)) return no(`pip option ${a} is not allowed`);
+                if (a === "." ) continue;
+                if (!PY_PKG.test(a)) return no(`'${a}' is not a plain package requirement (URLs / VCS / files are not allowed)`);
+                return no(`installing a named package requires approval (ADD_UNPINNED_DEPENDENCY): ${a}`);
+            }
+            return ok("pkg");
+        }
+        default:
+            return no(`pip ${sub || ""} is not allowed`);
+    }
+}
+
+function pythonFamily(argv, root, ecos) {
+    const tool = path.basename(argv[0]);
+    const e = needEco(ecos, "python", tool); if (e) return e;
+    const args = argv.slice(1);
+    if (/^pip3?$/.test(tool)) return pipArgs(args, root);
+    if (/^python(3(\.\d+)?)?$/.test(tool)) {
+        if (args.length === 1 && /^(-V|--version)$/.test(args[0])) return ok("pkg");
+        if (args[0] !== "-m") return no("python may only run allowed modules (python -m pytest|unittest|pip|mypy|ruff|…)");
+        const mod = args[1];
+        const rest = args.slice(2);
+        if (mod === "pip") return pipArgs(rest, root);
+        const pathErr = checkPaths(root, rest); if (pathErr) return pathErr;
+        if (/^(pytest|unittest|mypy|ruff|flake8|black|pylint|isort|compileall|py_compile|coverage|tox|nox)$/.test(mod || "")) return ok(/^(pytest|unittest|coverage|tox|nox)$/.test(mod) ? "test" : "lint");
+        return no(`python -m ${mod || ""} is not allowed`);
+    }
+    if (tool === "poetry" || tool === "uv") {
+        // only the subcommand's own options here; `run` validates its command recursively
+        const own = args[0] === "run" ? [] : args;
+        const pathErr = checkPaths(root, own); if (pathErr) return pathErr;
+    } else {
+        const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+    }
+    if (tool === "poetry") {
+        if (/^(install|check|show|lock|--version)$/.test(args[0] || "")) return ok("pkg");
+        if (args[0] === "run") return args.length > 1 ? evaluateArgv(args.slice(1), root, ecos, 1) : no("poetry run needs a command");
+        return no(`poetry ${args[0] || ""} is not allowed`);
+    }
+    if (tool === "uv") {
+        if (/^(sync|lock|--version)$/.test(args[0] || "")) return ok("pkg");
+        if (args[0] === "pip") return pipArgs(args.slice(1), root);
+        if (args[0] === "run") return args.length > 1 ? evaluateArgv(args.slice(1), root, ecos, 1) : no("uv run needs a command");
+        return no(`uv ${args[0] || ""} is not allowed`);
+    }
+    if (tool === "tox" || tool === "nox") return ok("test");
+    return no(`${tool} is not allowed`);
+}
+
+function goFamily(argv, root, ecos) {
+    const e = needEco(ecos, "go", "go"); if (e) return e;
+    const [sub, ...rest] = argv.slice(1);
+    if (rest.some(a => /^-(exec|toolexec|overlay|modfile)(=|$)/.test(a))) return no("go -exec/-toolexec/-overlay are not allowed");
+    const pathErr = checkPaths(root, rest); if (pathErr) return pathErr;
+    if (/^(build|test|vet|list|version|env|fmt)$/.test(sub || "")) return ok(sub === "test" ? "test" : "pkg");
+    if (sub === "mod" && /^(download|tidy|verify|graph|why)$/.test(rest[0] || "")) return ok("pkg");
+    return no(`go ${sub || ""} is not allowed`);
+}
+
+function cargoFamily(argv, root, ecos) {
+    const e = needEco(ecos, "rust", "cargo"); if (e) return e;
+    const [sub, ...rest] = argv.slice(1);
+    if (rest.some(a => /^--config(=|$)/.test(a))) return no("cargo --config is not allowed");
+    const pathErr = checkPaths(root, rest); if (pathErr) return pathErr;
+    if (/^(build|test|check|clippy|fmt|doc|tree|metadata|--version|fetch|bench)$/.test(sub || "")) return ok(sub === "test" ? "test" : "pkg");
+    return no(`cargo ${sub || ""} is not allowed`);
+}
+
+function dotnetFamily(argv, root, ecos) {
+    const e = needEco(ecos, "dotnet", "dotnet"); if (e) return e;
+    const [sub, ...rest] = argv.slice(1);
+    if (rest.some(a => /^(-s|--source|--configfile)(=|$)/.test(a))) return no("custom NuGet sources are not allowed");
+    const pathErr = checkPaths(root, rest); if (pathErr) return pathErr;
+    if (/^(build|test|restore|format|--info|--version|clean)$/.test(sub || "")) return ok(sub === "test" ? "test" : "pkg");
+    if (sub === "list" && rest.includes("package")) return ok("pkg");
+    return no(`dotnet ${sub || ""} is not allowed`);
+}
+
+/** A tool option / argument that points into .git/ or a hook dir (e.g. --outputFile=.git/hooks/x). */
+function toolingTargetsProtectedDir(root, args) {
+    for (const a of args) {
+        const v = a.startsWith("-") ? (a.includes("=") ? a.slice(a.indexOf("=") + 1) : "") : a;
+        if (!v || !/[\\/]|^\.(git|husky|githooks)$/.test(v)) continue;
+        let real;
+        try { real = confineToRoot(root, path.resolve(cwds(root)[0], v)); } catch { continue; }
+        const rel = path.relative(confineToRoot(root, "."), real).split(path.sep);
+        if (rel.some(x => x === ".git" || x === ".husky" || x === ".githooks")) return no(`'${a}' points into .git/ or a hook directory`);
+    }
+    return null;
+}
+
+// ─────────────────────────── wrappers ───────────────────────────
+// A wrapper (env, time, nice, timeout, c8, nyc, npx, poetry/uv run, npm exec)
+// runs ANOTHER command: that command is validated recursively against the
+// same policy. xargs builds its command from stdin and cannot be validated.
+
+const MAX_WRAP_DEPTH = 4;
+const COVERAGE_VALUE_FLAGS = /^(-r|--reporter|-o|--report-dir|--reports-dir|--temp-directory|--tempDirectory|-x|--exclude|-n|--include|-e|--extension|--src|--cwd|--config|--nycrc-path|--lines|--functions|--branches|--statements|--per-file|--check-coverage|--100|--skip-full|--all|--clean|--exclude-after-remap|--exclude-node-modules)$/;
+const COVERAGE_BOOL_FLAGS = /^(--per-file|--check-coverage|--100|--skip-full|--all|--clean|--exclude-after-remap|--silent|--no-clean|--exclude-node-modules|--source-map|--produce-source-map|--instrument|--cache|--no-cache|-h|--help|-v|--version)$/;
+
+function wrapperFamily(a, root, ecos, depth) {
+    const base = path.basename(a[0]);
+    const args = a.slice(1);
+    const recurse = (wrapped, what) => {
+        if (!wrapped.length) return no(`${base} needs a command to run`);
+        if (depth >= MAX_WRAP_DEPTH) return no("too many nested wrapper commands");
+        const r = evaluateArgv(wrapped, root, ecos, depth + 1);
+        return r.ok ? r : no(`${what || base} runs a command that is not allowed: ${r.reason}`);
+    };
+    switch (base) {
+        case "xargs":
+            return no("xargs builds commands from its input, which cannot be validated");
+        case "env": {
+            let i = 0;
+            for (; i < args.length; i++) {
+                const x = args[i];
+                if (x === "-i" || x === "--ignore-environment" || x === "-") continue;
+                if (x === "-u" || x === "--unset") { i++; continue; }
+                if (/^--unset=/.test(x)) continue;
+                if (isOpt(x)) return no(`env option ${x} is not allowed`);
+                if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(x)) { if (!ENV_OK.test(x)) return no(`environment assignment ${x.split("=")[0]}= is not allowed`); continue; }
+                break;
+            }
+            return recurse(args.slice(i));
+        }
+        case "time": {
+            let i = 0;
+            while (i < args.length && /^(-p|--portability)$/.test(args[i])) i++;
+            return recurse(args.slice(i));
+        }
+        case "nice": {
+            let i = 0;
+            for (; i < args.length; i++) {
+                if (args[i] === "-n" || args[i] === "--adjustment") { i++; continue; }
+                if (/^(-\d+|-n\d+|--adjustment=-?\d+)$/.test(args[i])) continue;
+                if (isOpt(args[i])) return no(`nice option ${args[i]} is not allowed`);
+                break;
+            }
+            return recurse(args.slice(i));
+        }
+        case "timeout": {
+            let i = 0;
+            for (; i < args.length; i++) {
+                if (args[i] === "-s" || args[i] === "--signal" || args[i] === "-k" || args[i] === "--kill-after") { i++; continue; }
+                if (/^(--preserve-status|--foreground|-v|--verbose|--signal=\w+|--kill-after=[\d.]+[smhd]?)$/.test(args[i])) continue;
+                if (isOpt(args[i])) return no(`timeout option ${args[i]} is not allowed`);
+                break;
+            }
+            if (!/^[\d.]+[smhd]?$/.test(args[i] || "")) return no("timeout needs a duration");
+            return recurse(args.slice(i + 1));
+        }
+        case "c8": case "nyc": {
+            if (!ecos.has("node")) return no(`${base} is only allowed in a workspace with a detected node project`);
+            let i = 0;
+            for (; i < args.length; i++) {
+                const x = args[i];
+                if (!isOpt(x)) break;
+                if (/^--[\w-]+=/.test(x) || /^-[a-zA-Z]=/.test(x)) { const pe = checkPaths(root, [x]); if (pe) return pe; continue; }
+                if (COVERAGE_BOOL_FLAGS.test(x)) continue;
+                if (COVERAGE_VALUE_FLAGS.test(x)) { const pe = checkPaths(root, [args[i + 1] || ""]); if (pe) return pe; i++; continue; }
+                return no(`${base} option ${x} is not allowed`);
+            }
+            const sub = args[i];
+            if (sub === "report" || sub === "check-coverage") {
+                const pe = checkPaths(root, args.slice(i + 1)); if (pe) return pe;
+                return ok("test");
+            }
+            const r = recurse(args.slice(i));
+            return r.ok ? ok("test") : r;
+        }
+        default:
+            return null;
+    }
+}
+
+/** Test runners / linters invoked directly (their binary must exist). */
+function standaloneRunner(argv, root, ecos) {
+    if (!argv.length) return no("empty command");
+    const tool = path.basename(argv[0]);
+    const args = argv.slice(1);
+    if (tool === "node") {
+        if (args.length === 1 && /^(-v|--version)$/.test(args[0])) return ok("pkg");
+        if (!args.includes("--test")) return no("node may only run the built-in test runner (node --test)");
+        if (args.some(a => /^(-e|--eval|-p|--print|-r|--require|--import|--loader|--experimental-loader)(=|$)/.test(a))) return no("node eval/preload options are not allowed");
+        const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+        return ok("test");
+    }
+    if (TEST_TOOLS.has(tool) || /^(pytest|py\.test)$/.test(tool)) {
+        if (args.some(a => /^[{[]/.test(a) || /^--[\w-]+=[{[]/.test(a))) return no(`${tool}: inline JSON configuration is not allowed`);
+        if (tool !== "pytest" && tool !== "py.test") { const rt = nodeRuntimeFlag(args); if (rt) return rt; }
+        if (tool === "pytest" || tool === "py.test") {
+            if (args.some(a => /^(-p|--pyargs|--rootdir|--confcutdir|-c|--config-file)(=|$)/.test(a))) return no("pytest -p/-c/--rootdir are not allowed");
+        }
+        const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+        const hook = toolingTargetsProtectedDir(root, args); if (hook) return hook;
+        return ok("test");
+    }
+    if (LINT_TOOLS.has(tool) || /^(ruff|flake8|black|mypy|pylint|isort|golangci-lint|gofmt|shellcheck|ktlint|hadolint|yamllint|markdownlint)$/.test(tool)) {
+        if (args.some(a => /^(--rulesdir|--resolve-plugins-relative-to|--plugin)(=|$)/.test(a) && tool === "eslint")) return no("eslint plugin/rules-dir options are not allowed");
+        const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+        const hook = toolingTargetsProtectedDir(root, args); if (hook) return hook;
+        return ok("lint");
+    }
+    return null;
+}
+
+// ─────────────────────────── family: files ───────────────────────────
+
+const READ_TOOLS = new Set(["cat", "head", "tail", "wc", "ls", "tree", "stat", "file", "du", "diff", "cmp", "pwd",
+    "echo", "basename", "dirname", "sort", "uniq", "cut", "tr", "jq", "nl", "true", "which", "column", "md5sum", "sha256sum", "shasum"]);
+const WRITE_TOOLS = new Set(["mkdir", "touch", "cp", "mv", "rm", "tee", "chmod"]);
+
+function fileFamily(argv, root) {
+    const tool = argv[0];
+    const args = argv.slice(1);
+    if (tool === "cd") {
+        if (args.length !== 1 || !inside(root, args[0])) return no("cd must target a directory inside the workspace root");
+        return ok("nav");
+    }
+    if (tool === "grep" || tool === "egrep" || tool === "fgrep" || tool === "rg") {
+        if (tool === "rg" && args.some(a => /^(--pre|--pre-glob|--search-zip|-z)(=|$)/.test(a))) return no("rg --pre is not allowed");
+        const pathErr = checkPaths(root, args, patternIndexes(args)); if (pathErr) return pathErr;
+        return ok("file-read");
+    }
+    if (tool === "find") {
+        if (args.some(a => /^-(exec|execdir|ok|okdir|delete|fprint|fprint0|fprintf|fls)$/.test(a))) return no("find actions (-exec/-delete/-fprint) are not allowed");
+        const skip = new Set();
+        args.forEach((a, i) => { if (/^-(name|iname|path|ipath|regex|iregex|wholename|newer|type|size|mtime|mmin|maxdepth|mindepth|user|group|perm)$/.test(a)) skip.add(i + 1); });
+        const pathErr = checkPaths(root, args, skip); if (pathErr) return pathErr;
+        return ok("file-read");
+    }
+    if (tool === "sed") {
+        // Only print-mode sed (sed -n '10,20p' file): the w/e/r commands write files or run shells.
+        const scripts = args.filter(a => !isOpt(a));
+        if (!args.includes("-n") || !scripts.length || !/^(\d+|\$)(,(\d+|\$))?p$/.test(scripts[0])) return no("sed is only allowed as sed -n '<start>,<end>p' <file>");
+        if (args.some(a => /^(-i|--in-place)/.test(a))) return no("sed -i requires approval");
+        const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+        return ok("file-read");
+    }
+    if (tool === "tail" && args.some(a => /^(-f|-F|--follow)/.test(a))) return no("tail -f is not allowed");
+    if (READ_TOOLS.has(tool)) {
+        if (tool === "sort" && args.some(a => /^(-o|--output)/.test(a))) {
+            const pathErr = checkPaths(root, args); if (pathErr) return pathErr;
+            for (let i = 0; i < args.length; i++) {
+                const m = args[i].match(/^(?:-o|--output)=?(.*)$/);
+                if (!m) continue;
+                const target = m[1] || args[i + 1];
+                const we = writeTargetError(root, "sort -o", target || ""); if (we) return we;
+            }
+            return ok("file-write");
+        }
+        const pathErr = checkPaths(root, args, tool === "echo" ? new Set(args.map((_, i) => i)) : new Set()); if (pathErr) return pathErr;
+        return ok("file-read");
+    }
+    if (WRITE_TOOLS.has(tool)) {
+        if (args.some(a => a === "--no-preserve-root")) return no("--no-preserve-root is not allowed");
+        const targets = args.filter(a => !isOpt(a) && !(tool === "chmod" && /^[0-7]{3,4}$|^[ugoa]*[+=-][rwxX]+$/.test(a)));
+        if (!targets.length) return no(`${tool} needs a target inside the workspace root`);
+        for (const t of targets) {
+            const we = writeTargetError(root, tool, t); if (we) return we;
+            if (tool === "rm" || tool === "mv" || tool === "chmod") {
+                const r = path.resolve(root, t);
+                if (r === path.resolve(root) || /^\.\/?$/.test(t)) return no(`${tool} of the workspace root itself is not allowed`);
+            }
+        }
+        return ok("file-write");
+    }
+    return null;
+}
+
+// ─────────────────────────────── evaluate ───────────────────────────────
+
+const ENV_OK = /^(CI|FORCE_COLOR|NO_COLOR|NODE_ENV|TZ|LANG|LC_ALL|PYTHONDONTWRITEBYTECODE)=[\w.:=-]*$/;
+
+/** Validates one argv. Returns { ok, family } or { ok: false, reason }. */
+export function evaluateArgv(argv, root, ecos = detectEcosystems(root), depth = 0) {
+    let a = argv.slice();
+    while (a.length && /^[A-Za-z_][A-Za-z0-9_]*=/.test(a[0])) {
+        if (!ENV_OK.test(a[0])) return no(`environment assignment ${a[0].split("=")[0]}= is not allowed`);
+        a = a.slice(1);
+    }
+    if (!a.length) return no("empty command");
+    const tool = a[0];
+    if (tool.includes("/") && !/^\.\/(mvnw|gradlew)$/.test(tool)) return no(`running '${tool}' by path is not allowed`);
+    const base = path.basename(tool);
+    if (base === "git") return gitFamily(a, root);
+    if (base === "npm" || base === "yarn" || base === "pnpm") return npmFamily(a, root, ecos);
+    if (base === "npx") return npxFamily(a, root, ecos, depth);
+    const w = wrapperFamily(a, root, ecos, depth);
+    if (w) return w;
+    if (base === "mvn" || base === "mvnw") return mavenFamily(a, root, ecos);
+    if (base === "gradle" || base === "gradlew") return gradleFamily(a, root, ecos);
+    if (/^(pip3?|python(3(\.\d+)?)?|poetry|uv|tox|nox)$/.test(base)) return pythonFamily(a, root, ecos);
+    if (base === "go") return goFamily(a, root, ecos);
+    if (base === "cargo") return cargoFamily(a, root, ecos);
+    if (base === "dotnet") return dotnetFamily(a, root, ecos);
+    const f = fileFamily(a, root) || standaloneRunner(a, root, ecos);
+    return f || no(`'${base}' is not in the command allowlist`);
+}
+
+/**
+ * Validates a shell command string. Returns { allowed, families, reason }.
+ */
+export function evaluateCommand(command, root, { ecosystems } = {}) {
+    if (!root) return { allowed: false, reason: "no workspace root" };
+    const t = tokenize(command);
+    if (!t.ok) return { allowed: false, reason: t.reason };
+    const ecos = ecosystems || detectEcosystems(root);
+    const prev = CWDS;
+    CWDS = [root];
+    try {
+        const families = [];
+        let wrote = false;
+        for (const seg of t.segments) {
+            for (let i = 0; i < seg.argv.length; i++) {
+                if (!seg.quoted[i] && GLOB.test(seg.argv[i])) {
+                    const g = checkShellGlob(root, seg.argv[i]);
+                    if (g) return { allowed: false, reason: g.reason, families };
+                }
+            }
+            const r = evaluateArgv(seg.argv, root, ecos);
+            if (!r.ok) return { allowed: false, reason: r.reason, families };
+            // A command string that writes files and THEN runs a build/test/lint
+            // tool could plant code for that tool: refuse the combination.
+            if (wrote && EXECUTING.has(r.family)) {
+                return { allowed: false, reason: "a command that writes files may not run build/test/lint tools afterwards in the same command (split it into separate calls)", families };
+            }
+            families.push(r.family);
+            let segWrites = r.family === "file-write";
+            for (const rd of seg.redirects) {
+                if (rd.op === ">&") { if (!/^[12]$/.test(rd.target)) return { allowed: false, reason: "only 2>&1 / 1>&2 duplication is allowed" }; continue; }
+                if (rd.target === "/dev/null") continue;
+                if (!inside(root, rd.target)) return { allowed: false, reason: `redirection target '${rd.target}' is outside the workspace root` };
+                if (rd.op !== "<") {
+                    const we = writeTargetError(root, "redirection", rd.target);
+                    if (we) return { allowed: false, reason: we.reason, families };
+                    families.push("file-write");
+                    segWrites = true;
+                }
+            }
+            if (segWrites) wrote = true;
+            // `cd` changes where later relative paths resolve: check against every candidate.
+            if (seg.argv[0] === "cd" && seg.argv[1]) CWDS = [...new Set([...CWDS, ...CWDS.map(c => path.resolve(c, seg.argv[1]))])];
+        }
+        return { allowed: true, families: [...new Set(families)] };
+    } finally {
+        CWDS = prev;
+    }
+}
+
+const EXECUTING = new Set(["pkg", "test", "lint"]);
+
+// ──────────────────────────── request decision ────────────────────────────
+
+/**
+ * Platform-authored tool commands (built by visionhammer-agents, not typed by
+ * the model). Accepted only when the request signature VERIFIED — the signed
+ * body names the tool. Everything the model types (run_command) is not in here.
+ */
+export const PLATFORM_TOOLS = Object.freeze(new Set([
+    "create_branch", "git_commit", "git_push", "close_pr", "delete_branch", "publish_scope", "current_branch",
+]));
+
+export function resolveExecPolicyConfig(env = process.env) {
+    return { mode: resolveMode(env.LOCAL_AGENT_EXEC_POLICY_MODE, "enforce") };
+}
+
+export const execStats = { allowed: 0, platform: 0, approved: 0, warned: 0, rejected: 0 };
+
+/**
+ * Decides one exec request. `command` (shell string) or `argv` (no shell).
+ * Returns { allow: boolean, status?, reason?, via }.
+ */
+export function decideExec({ command, argv, root, headers = {}, body = {}, vhSignature, signingCfg }, cfg = resolveExecPolicyConfig()) {
+    if (cfg.mode === "off") return { allow: true, via: "policy-off" };
+    const verdict = argv
+        ? (() => {
+            const prev = CWDS; CWDS = [root];
+            try { const r = evaluateArgv(argv, root); return r.ok ? { allowed: true, families: [r.family] } : { allowed: false, reason: r.reason }; }
+            finally { CWDS = prev; }
+        })()
+        : evaluateCommand(command, root);
+    if (verdict.allowed) { execStats.allowed++; return { allow: true, via: `allowlist:${verdict.families.join("+")}` }; }
+
+    if (body.commandOrigin === "platform" && PLATFORM_TOOLS.has(body.tool) && vhSignature?.verified) {
+        execStats.platform++;
+        return { allow: true, via: `platform-tool:${body.tool}` };
+    }
+
+    const approval = headers["x-vh-approval"] || body.approvalToken;
+    if (approval) {
+        const subject = argv ? JSON.stringify(argv) : command;
+        const a = verifyApprovalToken(approval, {
+            subject,
+            keys: signingCfg?.keys,
+            identity: signingCfg?.identity,
+            requestTenantId: vhSignature?.verified ? vhSignature.tenantId : undefined,
+            nonces: signingCfg?.approvalNonces || approvalNonces,
+            now: signingCfg?.now,
+        });
+        if (a.ok) { execStats.approved++; return { allow: true, via: `human-approval:${a.approvedBy || "unknown"}` }; }
+        verdict.reason = `${verdict.reason}; approval token rejected: ${a.reason}`;
+    }
+
+    const shown = (argv ? argv.join(" ") : command).slice(0, 120);
+    if (cfg.mode === "enforce") {
+        execStats.rejected++;
+        logDecision("warn", `exec-rej:${verdict.reason}`, `[exec-policy] REJECTED "${shown}": ${verdict.reason}`);
+        return { allow: false, status: 403, reason: verdict.reason, via: "rejected" };
+    }
+    execStats.warned++;
+    logDecision("warn", `exec-warn:${verdict.reason}`, `[exec-policy] WARN (would reject in enforce) "${shown}": ${verdict.reason}`);
+    return { allow: true, via: "warn", reason: verdict.reason };
+}
+
+/** Standard 403 body for a rejected command. */
+export function rejectionBody(decision) {
+    return {
+        ok: false,
+        error: "command not allowed by the agent's execution policy",
+        reason: decision.reason,
+        hint: "Allowed: read-only git, package-manager install/test/build for the detected ecosystem, "
+            + "test runners, linters, and file read/write inside the workspace root. Anything else needs "
+            + "a PolicyGate human approval (REQUIRE_HUMAN).",
+    };
+}