@mmerterden/multi-agent-pipeline 20.2.0 → 20.3.0

package/pipeline/scripts/unattended_policy.py

@@ -0,0 +1,2786 @@
+#!/usr/bin/env python3
+"""Unattended policy for agent-guard.py: what a run nobody is watching may not do.
+
+Consulted only when MULTI_AGENT_UNATTENDED=1 is in the hook's own environment,
+which the autopilot runner sets on the `claude` process it spawns. It is never
+read from agent-state.json: the run writes that file, and a rule the run can
+switch off is not a rule. With the variable unset this module is not imported.
+
+The model is refuse-what-it-cannot-parse. A Bash command is accepted only when
+it reduces to simple commands joined by `;`, `&&`, `||` and plain pipes between
+non-interpreter commands. Anything that hides a command from a line reader -
+a subshell, a group, a substitution, a heredoc, a background job, a shell
+keyword, a pipe into an interpreter, a `-c` on a shell - is refused outright,
+because the guard reads the command line and cannot judge what it cannot parse.
+The command families it can parse (git, gh, curl, installs, writes) are then
+checked against the lists in ../schemas/unattended-policy.json.
+
+Every check returns None (allowed) or a short reason string (blocked). Nothing
+here executes the inspected command; the only processes it starts are read-only
+`git` reads, memoized per invocation. Contract:
+multi-agent-refs/features/unattended-security.md.
+"""
+import json
+import os
+import re
+import shlex
+import stat
+from urllib.parse import urlsplit
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+POLICY_CANDIDATES = [
+    os.path.join(HERE, "..", "schemas", "unattended-policy.json"),
+    os.path.join(HERE, "..", "pipeline", "schemas", "unattended-policy.json"),
+]
+PR_REQUESTS_SUBDIR = "pr-requests"
+PR_VERDICT_SUFFIX = ".verdict.json"
+UNATTENDED_RUN_DIR = ".multi-agent-unattended"
+
+DARWIN = os.uname().sysname == "Darwin" if hasattr(os, "uname") else False
+MAX_SEGMENTS = 50
+
+# --- shell structure the guard refuses to reason about -----------------------
+
+# Command position tokens that are not simple commands.
+SHELL_KEYWORDS = {
+    "if", "then", "else", "elif", "fi", "for", "while", "until", "do", "done",
+    "case", "esac", "function", "select", "eval", "exec", "source", ".",
+    "export", "trap", "set", "unset", "alias", "unalias", "declare", "typeset",
+    "readonly", "let", "return", "coproc", "time",
+}
+SHELLS = {"sh", "bash", "zsh", "dash", "ksh", "fish"}
+INTERPRETERS = SHELLS | {"node", "perl", "ruby", "osascript", "php", "lua", "tclsh", "wish", "rscript"}
+# Wrappers that run the rest of the line as a command; their option values are
+# consumed so the wrapped command is what gets judged.
+WRAPPER_VALUE_OPTS = {
+    "env": {"-u", "-P", "--unset", "--block-signal", "--default-signal", "--ignore-signal"},
+    "nice": {"-n", "--adjustment"},
+    "timeout": {"-s", "--signal", "-k", "--kill-after"},
+    "gtimeout": {"-s", "--signal", "-k", "--kill-after"},
+    "ionice": {"-c", "-n", "-p"},
+    "nohup": set(),
+    "caffeinate": set(),
+    "command": set(),
+    "builtin": set(),
+    "stdbuf": {"-i", "-o", "-e"},
+    "xcrun": {"-sdk", "--sdk", "-toolchain", "--toolchain"},
+    "arch": {"-arch", "-d"},
+    "sandbox-exec": {"-f", "-n", "-p", "-D"},
+}
+# Wrappers whose command line the guard does not model: `script` takes an
+# output file before the command, `watch` hands its arguments to `sh -c`, a
+# debugger runs its target under its own control (and takes commands that spawn
+# a shell), and a job runner (parallel, xargs) or a locker (flock) hands the
+# rest to a shell or repeats it per input. `chroot` and `unbuffer` and the
+# traces run their target too. Each is refused rather than parsed.
+OPAQUE_WRAPPERS = {
+    "script", "watch",
+    "lldb", "gdb", "lldb-mi",
+    "parallel", "flock", "unbuffer", "chroot", "dtruss", "dtrace", "ktrace",
+    "strace", "ltrace", "rlwrap", "expect",
+    "automator", "shortcuts", "osacompile",
+}
+ENV_REFUSED_OPTS = ("-S", "--split-string", "-C", "--chdir")
+XCRUN_LOOKUPS = ("-f", "--find", "--show-sdk-path", "--show-sdk-version", "--show-sdk-build-version",
+                 "--show-sdk-platform-path", "--show-sdk-platform-version", "--version", "-version", "-h", "--help")
+
+
+def _is_interpreter(base):
+    return base in INTERPRETERS or base.startswith("python")
+
+
+def _casefold(s):
+    return s.casefold() if DARWIN else s
+
+
+def _strip_quotes(cmd, keep_double):
+    """cmd with quoted spans removed. keep_double keeps the CONTENT of
+    double-quoted spans (where `$(` and backticks stay active) while dropping
+    single-quoted spans (inert). A backslash escapes the next char outside
+    single quotes."""
+    out = []
+    q = None
+    i = 0
+    n = len(cmd)
+    while i < n:
+        c = cmd[i]
+        if q is None:
+            if c == "\\" and i + 1 < n:
+                i += 2
+                continue
+            if c == "'":
+                q = "'"
+            elif c == '"':
+                q = '"'
+            else:
+                out.append(c)
+        elif q == "'":
+            if c == "'":
+                q = None
+        else:  # double quote
+            if c == "\\" and i + 1 < n:
+                if keep_double:
+                    out.append(cmd[i + 1])
+                i += 2
+                continue
+            if c == '"':
+                q = None
+            elif keep_double:
+                out.append(c)
+        i += 1
+    return "".join(out)
+
+
+class Refused(Exception):
+    """The line uses shell syntax the guard does not analyse."""
+
+
+PLACEHOLDER_RX = re.compile(r"__MA_SUBST_(\d+)__", re.I)
+
+
+def _placeholder(k):
+    return f"__MA_SUBST_{k}__"
+
+
+def _has_ph(s):
+    return bool(s) and bool(PLACEHOLDER_RX.search(s))
+
+
+def _match_paren(cmd, start):
+    """Index of the `)` closing a `$(` whose body starts at `start`. Quote-aware
+    and balanced; a nested `$(` or an unterminated body is refused."""
+    depth = 1
+    q = None
+    i = start
+    n = len(cmd)
+    while i < n:
+        c = cmd[i]
+        if q == "'":
+            if c == "'":
+                q = None
+            i += 1
+            continue
+        if c == "\\" and i + 1 < n:
+            i += 2
+            continue
+        if q == '"':
+            if c == '"':
+                q = None
+            elif c == "$" and cmd.startswith("$(", i):
+                raise Refused("a command substitution nested inside another is not analysed")
+            elif c == "`":
+                raise Refused("a backtick substitution hides a command from the guard")
+            i += 1
+            continue
+        if c in ("'", '"'):
+            q = c
+        elif c == "$" and cmd.startswith("$(", i):
+            raise Refused("a command substitution nested inside another is not analysed")
+        elif c == "(":
+            depth += 1
+        elif c == ")":
+            depth -= 1
+            if depth == 0:
+                return i
+        i += 1
+    raise Refused("an unterminated command substitution cannot be parsed")
+
+
+HEREDOC_TOKEN = "__MA_HEREDOC__"
+
+
+def _heredoc_delim(cmd, i):
+    """At an unquoted `<<` (not `<<<`): (end, delimiter, dash, quoted)."""
+    j = i + 2
+    dash = j < len(cmd) and cmd[j] == "-"
+    if dash:
+        j += 1
+    while j < len(cmd) and cmd[j] in " \t":
+        j += 1
+    if j < len(cmd) and cmd[j] in ("'", '"'):
+        qc = cmd[j]
+        k = cmd.find(qc, j + 1)
+        if k < 0:
+            raise Refused("an unterminated heredoc delimiter cannot be parsed")
+        return k + 1, cmd[j + 1:k], dash, True
+    quoted = j < len(cmd) and cmd[j] == "\\"
+    if quoted:
+        j += 1
+    m = re.match(r"[A-Za-z0-9_.-]+", cmd[j:])
+    if not m:
+        raise Refused("a heredoc without a readable delimiter cannot be parsed")
+    return j + m.end(), m.group(0), dash, quoted
+
+
+def strip_heredocs(cmd):
+    """cmd with every heredoc body removed and its `<<'DELIM'` replaced by an
+    input redirect from a placeholder. A body behind a quoted delimiter is
+    literal data. An unquoted delimiter expands `$(...)` inside the body, which
+    the guard does not analyse, so it is refused. Quote-aware, and `$(` opens a
+    fresh quoting context the way the shell does."""
+    out = []
+    i = 0
+    n = len(cmd)
+    q = None
+    stack = []
+    depth = 0
+    pending = []
+    while i < n:
+        c = cmd[i]
+        if q == "'":
+            out.append(c)
+            if c == "'":
+                q = None
+            i += 1
+            continue
+        if c == "\\" and i + 1 < n:
+            out.append(cmd[i:i + 2])
+            i += 2
+            continue
+        if q == '"':
+            if c == '"':
+                q = None
+            elif cmd.startswith("$(", i):
+                stack.append((q, depth))
+                q, depth = None, 0
+                out.append("$(")
+                i += 2
+                continue
+            out.append(c)
+            i += 1
+            continue
+        if c in ("'", '"'):
+            q = c
+            out.append(c)
+            i += 1
+            continue
+        if cmd.startswith("$(", i):
+            stack.append((None, depth))
+            depth = 0
+            out.append("$(")
+            i += 2
+            continue
+        if c == "(":
+            depth += 1
+        elif c == ")":
+            if depth == 0 and stack:
+                q, depth = stack.pop()
+                out.append(c)
+                i += 1
+                continue
+            depth -= 1
+        if cmd.startswith("<<", i) and not cmd.startswith("<<<", i) and not (i > 0 and cmd[i - 1] == "<"):
+            end, delim, dash, quoted = _heredoc_delim(cmd, i)
+            if not quoted:
+                raise Refused("a heredoc with an unquoted delimiter expands its body, which the guard does not analyse")
+            out.append(f"< {HEREDOC_TOKEN} ")
+            pending.append((delim, dash))
+            i = end
+            continue
+        if c == "\n" and pending:
+            out.append("\n")
+            i += 1
+            for delim, dash in pending:
+                while True:
+                    if i >= n:
+                        raise Refused("an unterminated heredoc cannot be parsed")
+                    k = cmd.find("\n", i)
+                    line = cmd[i:] if k < 0 else cmd[i:k]
+                    i = n if k < 0 else k + 1
+                    if (line.lstrip("\t") if dash else line) == delim:
+                        break
+            pending = []
+            continue
+        out.append(c)
+        i += 1
+    if pending:
+        raise Refused("an unterminated heredoc cannot be parsed")
+    return "".join(out)
+
+
+def extract_substitutions(cmd):
+    """(outer, inners): every top-level `$(...)` replaced by an indexed
+    placeholder, and the inner command texts. Single-quoted text is literal.
+    `$((` arithmetic and an unbalanced quote are refused."""
+    out = []
+    inners = []
+    q = None
+    i = 0
+    n = len(cmd)
+    while i < n:
+        c = cmd[i]
+        if q == "'":
+            out.append(c)
+            if c == "'":
+                q = None
+            i += 1
+            continue
+        if c == "\\" and i + 1 < n:
+            out.append(cmd[i:i + 2])
+            i += 2
+            continue
+        if c == '"':
+            q = None if q == '"' else '"'
+            out.append(c)
+            i += 1
+            continue
+        if c == "'" and q is None:
+            q = "'"
+            out.append(c)
+            i += 1
+            continue
+        if c == "$" and cmd.startswith("$((", i):
+            raise Refused("arithmetic expansion $((...)) is not analysed")
+        if c == "$" and cmd.startswith("$(", i):
+            j = _match_paren(cmd, i + 2)
+            inners.append(cmd[i + 2:j])
+            out.append(_placeholder(len(inners) - 1))
+            i = j + 1
+            continue
+        out.append(c)
+        i += 1
+    if q is not None:
+        raise Refused("an unbalanced quote leaves the command unparseable")
+    return "".join(out), inners
+
+
+BACKGROUND = re.compile(r"(?<![&>0-9])&(?![&>])")
+SUBST = re.compile(r"\$\(|`|<\(|>\(")
+HEREDOC = re.compile(r"(?<!<)<<(?!<)")
+GROUPING = re.compile(r"[(){}]")
+OP_SPLIT = re.compile(r"\|\||&&|;|\n|\|")
+
+
+def split_ops(cmd):
+    """The simple-command segments of a line, split on unquoted `;`, `&&`,
+    `||`, `|`, `|&` and newlines - the way the shell splits them, so an
+    operator inside a quoted sed, jq or awk program is not a separator."""
+    segs = []
+    cur = []
+    q = None
+    i = 0
+    n = len(cmd)
+    while i < n:
+        c = cmd[i]
+        if q == "'":
+            cur.append(c)
+            if c == "'":
+                q = None
+            i += 1
+            continue
+        if c == "\\" and i + 1 < n:
+            cur.append(cmd[i:i + 2])
+            i += 2
+            continue
+        if q == '"':
+            cur.append(c)
+            if c == '"':
+                q = None
+            i += 1
+            continue
+        if c in ("'", '"'):
+            q = c
+            cur.append(c)
+            i += 1
+            continue
+        two = cmd[i:i + 2]
+        if two in ("&&", "||", "|&"):
+            segs.append("".join(cur))
+            cur = []
+            i += 2
+            continue
+        if c == "|" and cur and cur[-1] == ">":
+            cur.append(c)
+            i += 1
+            continue
+        if c in (";", "|", "\n"):
+            segs.append("".join(cur))
+            cur = []
+            i += 1
+            continue
+        cur.append(c)
+        i += 1
+    segs.append("".join(cur))
+    return segs
+
+
+WRITE_REDIRECTS = {">", ">>", ">|", "&>", "&>>", "<>"}
+
+
+def redirect_targets(seg):
+    """Files a segment's redirections write, read with a quote-aware lexer so a
+    `>` inside quotes is text and a quoted target is still seen."""
+    try:
+        lex = shlex.shlex(seg, posix=True, punctuation_chars=True)
+        lex.whitespace_split = True
+        toks = list(lex)
+    except ValueError:
+        raise Refused("an unbalanced quote leaves the redirections unparseable")
+    out = []
+    for i, t in enumerate(toks):
+        if i + 1 >= len(toks):
+            continue
+        nxt = toks[i + 1]
+        if t in WRITE_REDIRECTS:
+            out.append(nxt)
+        elif t == ">&" and not (nxt.isdigit() or nxt == "-"):
+            out.append(nxt)
+    return out
+
+
+SIMPLE_PARAM = re.compile(r"\$\{[A-Za-z_][A-Za-z0-9_]*\}")
+
+
+def structural_refusal(cmd):
+    """A reason the command cannot be reduced to simple commands, or None.
+    Called after heredoc bodies are stripped and `$(...)` extracted, so what is
+    left of `<<` is a here-string and any `$(` left is unanalysable."""
+    meta = SIMPLE_PARAM.sub("$P", _strip_quotes(cmd, keep_double=False))
+    subst = _strip_quotes(cmd, keep_double=True)
+    if SUBST.search(subst):
+        return "a backtick or process substitution hides a command from the guard"
+    if HEREDOC.search(meta):
+        return "a heredoc the guard could not strip feeds a command it cannot see"
+    if GROUPING.search(meta):
+        return "a subshell, brace group or non-trivial ${...} expansion hides a command from the guard"
+    if BACKGROUND.search(meta):
+        return "a background job (&) runs a command the guard cannot wait on"
+    segs = split_ops(cmd)
+    if len(segs) > MAX_SEGMENTS:
+        return f"the command has more than {MAX_SEGMENTS} segments and is refused unparsed"
+    return None
+
+
+def tokenize(text):
+    try:
+        return shlex.split(text)
+    except ValueError:
+        return text.split()
+
+
+ASSIGN_NAME = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=")
+
+
+def _walk_wrappers(toks):
+    """(assignments, command, refusal) for a token list: the VAR=value
+    assignments that apply to the command (leading ones, those after `env`,
+    and `arch -e` values), the wrapped command with every wrapper and its
+    option values consumed, and a reason when a wrapper hides the command."""
+    assigns = []
+    i = 0
+    while i < len(toks):
+        t = toks[i]
+        if ASSIGN_NAME.match(t):
+            assigns.append(t)
+            i += 1
+            continue
+        base = os.path.basename(t).lower()
+        if base in OPAQUE_WRAPPERS:
+            return assigns, toks[i:], f"{base} runs the rest of the line in a way the guard does not model"
+        if base not in WRAPPER_VALUE_OPTS:
+            break
+        value_opts = WRAPPER_VALUE_OPTS[base]
+        i += 1
+        while i < len(toks) and toks[i].startswith("-"):
+            opt = toks[i]
+            i += 1
+            if base == "env" and any(opt == o or opt.startswith(o + ("=" if o.startswith("--") else "")) for o in ENV_REFUSED_OPTS):
+                return assigns, toks[i:], "env -S / -C re-splits the command or moves it to another directory"
+            if base == "arch" and opt == "-e":
+                if i < len(toks):
+                    assigns.append(toks[i])
+                    i += 1
+                continue
+            if base == "xcrun" and (opt in XCRUN_LOOKUPS or opt.startswith("--show-sdk")):
+                return assigns, [], None
+            if opt in value_opts and i < len(toks):
+                i += 1
+        # timeout takes a bare DURATION positional before the command.
+        if base in ("timeout", "gtimeout") and i < len(toks) and re.match(r"^[0-9]", toks[i]):
+            i += 1
+    return assigns, toks[i:], None
+
+
+def _strip_wrappers(toks):
+    """Drop env assignments and wrappers that run the rest as a command,
+    consuming each wrapper's option VALUES so the wrapped command survives
+    intact. sudo, doas, xargs-with-a-command and shell keywords are NOT
+    stripped here; they are refused by simple_command_refusal."""
+    return _walk_wrappers(toks)[1]
+
+
+REDIR_TOKEN = re.compile(r"^\d*(>>|>\||>&|>|<<<|<>|<&|<|&>>|&>)(.*)$")
+INTERP_VALUE_OPTS = {"-r", "--require", "--import", "--loader", "--experimental-loader", "--input-type",
+                     "-C", "--conditions", "-W", "-X", "-I", "-M"}
+INTERP_INLINE = {"-e", "-E", "-p", "--eval", "--print"}
+
+
+def _operands(args):
+    """args with redirection operators and their targets removed."""
+    out = []
+    i = 0
+    while i < len(args):
+        m = REDIR_TOKEN.match(args[i])
+        if m:
+            i += 1 if m.group(2) else 2
+            continue
+        out.append(args[i])
+        i += 1
+    return out
+
+
+def _program_source(low, args):
+    """What an interpreter runs: "script" (a named file or module), "inline"
+    (code on the command line), or "stdin" (no program named, so it reads the
+    program from its input - a pipe, here-string or heredoc)."""
+    ops = _operands(args)
+    j = 0
+    while j < len(ops):
+        a = ops[j]
+        if a == "--":
+            return ("script", ops[j + 1]) if j + 1 < len(ops) else ("stdin", "")
+        if a == "-":
+            return "stdin", ""
+        if a.startswith("-"):
+            if low.startswith("python") and a == "-m":
+                return ("module", ops[j + 1]) if j + 1 < len(ops) else ("stdin", "")
+            if a in INTERP_INLINE:
+                return "inline", ""
+            if low in ("sh", "bash", "zsh", "dash", "ksh", "fish") and a == "-s":
+                return "stdin", ""
+            j += 2 if a in INTERP_VALUE_OPTS else 1
+            continue
+        return "script", a
+    return "stdin", ""
+
+
+_TRACK_CACHE = {}
+
+
+def _run_base_sha(env=None):
+    env = os.environ if env is None else env
+    sha = (env.get("MA_RUN_BASE_SHA") or "").strip()
+    return sha if re.match(r"^[0-9a-f]{7,40}$", sha) else None
+
+
+def _worktree_top(d):
+    try:
+        import subprocess
+
+        r = subprocess.run(["git", "-C", d, "rev-parse", "--show-toplevel"],
+                           capture_output=True, text=True, timeout=3)
+        return os.path.realpath(r.stdout.strip()) if r.returncode == 0 and r.stdout.strip() else None
+    except Exception:
+        return None
+
+
+def _tracked_clean(path, env=None, cwd=None):
+    """path is a regular file the run may run as a program: it is tracked by
+    git, unchanged in the working tree, AND present unchanged at the run's BASE
+    commit (MA_RUN_BASE_SHA). A file the run committed itself is clean against
+    HEAD but is not in the base, so it does not count. The path must sit inside
+    the RUN's worktree (the one cwd is in); a file in another clone that happens
+    to share the base commit does not count. Without a base sha the guard cannot
+    prove provenance, so it refuses."""
+    p = os.path.realpath(path)
+    key = (p, _run_base_sha(env) or "", os.path.realpath(cwd) if cwd else "")
+    if key in _TRACK_CACHE:
+        return _TRACK_CACHE[key]
+    ok = False
+    base = _run_base_sha(env)
+    run_top = _worktree_top(cwd) if cwd else None
+    if base and os.path.isfile(p):
+        d, name = os.path.split(p)
+        if run_top is not None and _worktree_top(d) != run_top:
+            _TRACK_CACHE[key] = False
+            return False
+        try:
+            import subprocess
+
+            def g(*a):
+                return subprocess.run(["git", "-C", d, *a], capture_output=True, text=True, timeout=3)
+
+            # The file's path relative to the worktree root, so the base lookup
+            # names it correctly and a file outside this worktree is rejected.
+            top = g("rev-parse", "--show-toplevel")
+            ls = g("ls-files", "--error-unmatch", "--", name)
+            st = g("status", "--porcelain", "--untracked-files=all", "--", name)
+            in_worktree = top.returncode == 0 and bool(top.stdout.strip())
+            rel = os.path.relpath(p, os.path.realpath(top.stdout.strip())) if in_worktree else None
+            at_base = (
+                g("cat-file", "-e", f"{base}:{rel}").returncode == 0
+                and g("diff", "--quiet", base, "--", name).returncode == 0
+                if rel and not rel.startswith("..")
+                else False
+            )
+            ok = (
+                in_worktree
+                and ls.returncode == 0
+                and st.returncode == 0
+                and not st.stdout.strip()
+                and at_base
+            )
+        except Exception:
+            ok = False
+    _TRACK_CACHE[key] = ok
+    return ok
+
+
+GLOB_CHARS = "*?["
+
+
+def _program_refusal(what, raw, cwd, variables, env):
+    """Reason `what` may not run the file `raw`, or None. A run may execute the
+    installed pipeline (~/.claude/scripts, ~/.claude/lib), a file it cannot
+    write, a binary npm linked into node_modules/.bin, or a file committed at
+    HEAD and left unmodified - never a file the run itself wrote or edited."""
+    e = expand(raw, variables or {}, env)
+    if e is None:
+        return f"{what} runs a file whose name is built at run time"
+    if any(ch in e for ch in GLOB_CHARS):
+        return f"{what} runs a file named by a glob pattern"
+    e = os.path.expanduser(re.sub(r"^\$\{?HOME\}?(?=/|$)", home(), e))
+    if not os.path.isabs(e) and cwd is None:
+        return f"{what} runs a file relative to a directory the guard could not resolve"
+    literal = os.path.normpath(e if os.path.isabs(e) else os.path.join(cwd, e))
+    real = os.path.realpath(literal)
+    # A program under /dev (/dev/stdin, /dev/fd/N) or any non-regular file
+    # (a FIFO, a device) is the program the guard cannot see: its bytes are the
+    # command's own input, not a file on disk it can judge.
+    if literal == "/dev" or literal.startswith("/dev/") or real == "/dev" or real.startswith("/dev/"):
+        return f"{what} runs a program read from {raw[:40]}, which the guard cannot see"
+    try:
+        st = os.stat(real)
+        if not stat.S_ISREG(st.st_mode):
+            return f"{what} runs {raw[:40]}, which is not a regular file (a FIFO, device or socket)"
+    except OSError:
+        pass
+    for h in {home(), os.path.expanduser("~")}:
+        for sub in ("scripts", "lib"):
+            base = os.path.join(h, ".claude", sub)
+            if _under(literal, base) or _under(real, os.path.realpath(base)):
+                return None
+    if (os.sep + os.path.join("node_modules", ".bin") + os.sep) in literal:
+        return None
+    if os.path.exists(real) and not os.access(real, os.W_OK) and not os.access(os.path.dirname(real), os.W_OK):
+        return None
+    if _tracked_clean(real, env, cwd):
+        return None
+    return (f"{what} runs {raw[:60]}, which is neither an installed pipeline script nor a file "
+            "committed unmodified at the run's base commit")
+
+
+# Interpreter options that put the program on the command line, by interpreter:
+# (short letters that mean "inline code", short letters that take a value and
+# end the cluster). python -c and sh -c are covered by the `-c` rule.
+INLINE_SHORT = {
+    "node": ("ep", "r"),
+    "bun": ("ep", "r"),
+    "ruby": ("e", "IrCEFKTWx0"),
+    "perl": ("eE", "IMmixCdD"),
+    "lua": ("e", "l"),
+    "osascript": ("e", "l"),
+    "swift": ("e", ""),
+    "rscript": ("e", ""),
+    "php": ("rRBE", "cdzfF"),
+}
+INLINE_LONG = {"--eval", "--print"}
+
+
+def _inline_flag(low, args):
+    if low not in INLINE_SHORT:
+        return None
+    inline, valued = INLINE_SHORT[low]
+    for a in args:
+        if a == "--":
+            return None
+        if a.split("=", 1)[0] in INLINE_LONG and low in ("node", "bun"):
+            return a
+        if a.startswith("-") and not a.startswith("--") and len(a) > 1:
+            for ch in a[1:]:
+                if ch in inline:
+                    return a
+                if ch in valued:
+                    break
+        elif not a.startswith("-"):
+            return None
+    return None
+
+
+SCRIPT_EXT = re.compile(r"\.(m?js|cjs|ts|tsx|jsx|mts|cts)$")
+
+
+def _module_refusal(what, name, cwd, variables, env):
+    """python -m NAME imports NAME from the cwd first: a module the run wrote
+    there is a file the run executes."""
+    if cwd is None:
+        return f"{what} imports a module relative to a directory the guard could not resolve"
+    first = name.split(".", 1)[0]
+    for cand in (first + ".py", first):
+        if os.path.exists(os.path.join(cwd, cand)):
+            return _program_refusal(what, cand, cwd, variables, env)
+    return None
+
+
+NODE_PRELOAD_OPTS = ("-r", "--require", "--import", "--loader", "--experimental-loader")
+
+
+def _node_preload_refusal(base, args, cwd, variables, env):
+    """node -r / --require / --import / --loader FILE runs FILE before the main
+    script; a file the run wrote there executes just as a script argument would.
+    The value is checked with _program_refusal."""
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--":
+            break
+        val = None
+        for opt in NODE_PRELOAD_OPTS:
+            if a == opt and i + 1 < len(args):
+                val = args[i + 1]
+                i += 1
+                break
+            if a.startswith(opt + "="):
+                val = a.split("=", 1)[1]
+                break
+        if val is not None:
+            if "://" in val:
+                return f"{base} {a.split('=', 1)[0]} preloads a remote module"
+            r = _program_refusal(f"{base} {a.split('=', 1)[0]}", val, cwd, variables, env)
+            if r:
+                return r
+        i += 1
+    return None
+
+
+def interpreter_refusal(stripped, cwd, variables=None, env=None):
+    """What an interpreter runs must be a file the run did not write: inline
+    code (-e, --eval, -p, php -r, deno eval) is refused, a script file is
+    checked with _program_refusal, and deno, bun and swift are judged by
+    their subcommand."""
+    base = os.path.basename(stripped[0])
+    low = base.lower()
+    args = stripped[1:]
+    flag = _inline_flag(low, args)
+    if flag:
+        return f"{base} {flag} runs an inline program the guard cannot see"
+    plains = [a for a in _operands(args) if not a.startswith("-")]
+    if low == "deno":
+        sub = plains[0] if plains else ""
+        if sub in ("eval", "repl"):
+            return f"deno {sub} runs an inline program the guard cannot see"
+        target = plains[1] if sub == "run" and len(plains) > 1 else (sub if SCRIPT_EXT.search(sub) or "/" in sub else "")
+        if target:
+            if "://" in target:
+                return "deno runs a remote module"
+            return _program_refusal(base, target, cwd, variables, env)
+        return None
+    if low == "bun":
+        sub = plains[0] if plains else ""
+        target = plains[1] if sub == "run" and len(plains) > 1 else ("" if sub == "run" else sub)
+        if target and (SCRIPT_EXT.search(target) or "/" in target):
+            return _program_refusal(base, target, cwd, variables, env)
+        return None
+    if low == "swift":
+        sub = plains[0] if plains else ""
+        if sub and (sub.endswith(".swift") or "/" in sub):
+            return _program_refusal(base, sub, cwd, variables, env)
+        return None
+    if low in ("node", "nodejs"):
+        r = _node_preload_refusal(base, args, cwd, variables, env)
+        if r:
+            return r
+    if not _is_interpreter(low):
+        return None
+    for a in args:
+        if a.startswith("-") and not a.startswith("--") and "c" in a[1:]:
+            return f"{base} -c runs an inline program the guard cannot see"
+    kind, script = _program_source(low, args)
+    if kind == "stdin":
+        return f"{base} with no script reads its program from stdin (a pipe, here-string or heredoc)"
+    if kind == "inline" and not low.startswith("python"):
+        return f"{base} runs an inline program the guard cannot see"
+    if _has_ph(script):
+        return f"{base} runs a script whose name is built at run time"
+    if kind == "module":
+        return _module_refusal(base, script, cwd, variables, env)
+    if kind == "script":
+        return _program_refusal(base, script, cwd, variables, env)
+    return None
+
+
+AWKS = {"awk", "gawk", "mawk", "nawk"}
+AWK_DANGER = re.compile(r"\bsystem\s*\(|(?<!\|)\|(?!\|)|\bgetline\b|\bprintf?\b[^;{}]*>|@load|@include")
+
+
+def awk_refusal(stripped, cwd, variables=None, env=None):
+    """An awk program may not start commands (system, a pipe, getline) or
+    write files (print > file); a program file must be one the run did not
+    write."""
+    args = stripped[1:]
+    progs, files = [], []
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a == "--":
+            i += 1
+            break
+        if not a.startswith("-") or a == "-":
+            break
+        key = a.split("=", 1)[0]
+        if key in ("-i", "--include", "-l", "--load", "-E", "--exec"):
+            return f"awk {key} loads code the guard cannot see"
+        if a in ("-f", "--file", "-e", "--source") and i + 1 < len(args):
+            (files if a in ("-f", "--file") else progs).append(args[i + 1])
+            i += 2
+            continue
+        if key in ("--file", "--source") and "=" in a:
+            (files if key == "--file" else progs).append(a.split("=", 1)[1])
+        elif a.startswith("-f") and len(a) > 2:
+            files.append(a[2:])
+        elif a in ("-F", "-v") and i + 1 < len(args):
+            i += 1
+        i += 1
+    if not files and not progs and i < len(args):
+        progs.append(args[i])
+    for f in files:
+        r = _program_refusal("awk -f", f, cwd, variables, env)
+        if r:
+            return r
+    for p in progs:
+        if AWK_DANGER.search(p):
+            return "an awk program with system, a pipe, getline or an output redirect runs or writes what the guard cannot see"
+    return None
+
+
+def _skip_sed_regex(s, i, delim):
+    n = len(s)
+    while i < n and s[i] != delim:
+        if s[i] == "\\":
+            i += 1
+        elif s[i] == "\n":
+            break
+        i += 1
+    return i + 1
+
+
+def sed_program_refusal(script):
+    """A sed program that writes a file (w, W, the s///w flag) or runs a
+    command (e, the s///e flag). A light scanner: it walks addresses and
+    commands, skipping regex and replacement text."""
+    s = script
+    n = len(s)
+    i = 0
+    reason = "a sed program with a w or e command writes a file or runs a command the guard cannot see"
+    while i < n:
+        if s[i] in " \t\n;{}!":
+            i += 1
+            continue
+        for _ in range(2):
+            if i < n and s[i].isdigit():
+                while i < n and (s[i].isdigit() or s[i] == "~"):
+                    i += 1
+            elif i < n and s[i] == "$":
+                i += 1
+            elif i < n and s[i] == "/":
+                i = _skip_sed_regex(s, i + 1, "/")
+                while i < n and s[i] in "IM":
+                    i += 1
+            elif i < n - 1 and s[i] == "\\":
+                i = _skip_sed_regex(s, i + 2, s[i + 1])
+            else:
+                break
+            while i < n and s[i] in " \t":
+                i += 1
+            if i < n and s[i] == ",":
+                i += 1
+                while i < n and s[i] in " \t":
+                    i += 1
+                continue
+            break
+        while i < n and s[i] in " \t!":
+            i += 1
+        if i >= n:
+            break
+        c = s[i]
+        if c in "wWe":
+            return reason
+        if c in "sy" and i + 1 < n:
+            d = s[i + 1]
+            i = _skip_sed_regex(s, i + 2, d)
+            i = _skip_sed_regex(s, i, d)
+            if c == "s":
+                j = i
+                while j < n and s[j] not in ";\n} \t":
+                    j += 1
+                if "w" in s[i:j] or "e" in s[i:j]:
+                    return reason
+                i = j
+            continue
+        if c in "aicrR":
+            k = s.find("\n", i)
+            i = n if k < 0 else k + 1
+            continue
+        if c in "btT:":
+            while i < n and s[i] not in ";\n":
+                i += 1
+            continue
+        i += 1
+    return None
+
+
+def sed_refusal(stripped, cwd, variables=None, env=None):
+    args = stripped[1:]
+    progs, files, ops = [], [], []
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in ("-e", "--expression") and i + 1 < len(args):
+            progs.append(args[i + 1])
+            i += 2
+            continue
+        if a.startswith("--expression="):
+            progs.append(a.split("=", 1)[1])
+        elif a.startswith("-e") and len(a) > 2 and not a.startswith("--"):
+            progs.append(a[2:])
+        elif a in ("-f", "--file") and i + 1 < len(args):
+            files.append(args[i + 1])
+            i += 2
+            continue
+        elif a.startswith("--file="):
+            files.append(a.split("=", 1)[1])
+        elif a == "-i" and i + 1 < len(args) and (args[i + 1] == "" or (args[i + 1].startswith(".") and "/" not in args[i + 1])):
+            i += 2
+            continue
+        elif a in ("-l", "--line-length") and i + 1 < len(args):
+            i += 2
+            continue
+        elif not a.startswith("-") or a == "-":
+            ops.append(a)
+        i += 1
+    if not progs and not files and ops:
+        progs.append(ops[0])
+    for f in files:
+        r = _program_refusal("sed -f", f, cwd, variables, env)
+        if r:
+            return r
+    for p in progs:
+        r = sed_program_refusal(p)
+        if r:
+            return r
+    return None
+
+
+MAKEFILES = ("GNUmakefile", "makefile", "Makefile")
+
+
+def make_refusal(stripped, cwd, variables=None, env=None):
+    """make runs the recipes of a Makefile: it has to be one committed
+    unmodified at HEAD, and the command line may not add code (--eval) or
+    override a variable a recipe expands (CC=...)."""
+    args = stripped[1:]
+    files, directory = [], None
+    i = 0
+    while i < len(args):
+        a = args[i]
+        key = a.split("=", 1)[0]
+        if key in ("-E", "--eval"):
+            return "make --eval adds rules the guard cannot see"
+        if a in ("-f", "--file", "--makefile") and i + 1 < len(args):
+            files.append(args[i + 1])
+            i += 2
+            continue
+        if key in ("--file", "--makefile") and "=" in a:
+            files.append(a.split("=", 1)[1])
+        elif a.startswith("-f") and len(a) > 2:
+            files.append(a[2:])
+        elif a in ("-C", "--directory") and i + 1 < len(args):
+            directory = args[i + 1]
+            i += 2
+            continue
+        elif key == "--directory" and "=" in a:
+            directory = a.split("=", 1)[1]
+        elif a.startswith("-C") and len(a) > 2:
+            directory = a[2:]
+        elif a in ("-I", "--include-dir", "-o", "-W", "--old-file", "--what-if", "--new-file", "--assume-old", "--assume-new") and i + 1 < len(args):
+            i += 2
+            continue
+        elif not a.startswith("-") and "=" in a:
+            return f"make {key}=... overrides a variable a recipe runs"
+        i += 1
+    base = cwd
+    if directory is not None:
+        e = expand(directory, variables or {}, env)
+        if e is None or (cwd is None and not os.path.isabs(e)):
+            return "make -C into a directory the guard could not resolve"
+        base = os.path.join(cwd or "/", os.path.expanduser(e))
+    if base is None:
+        return "make in a directory the guard could not resolve"
+    if not files:
+        try:
+            entries = os.listdir(base)
+        except OSError:
+            entries = []
+        found = [e for m in MAKEFILES for e in entries if _casefold(e) == _casefold(m)]
+        files = found[:1]
+    for f in files:
+        r = _program_refusal("make", f, base, variables, env)
+        if r:
+            return r
+    return None
+
+
+def simple_command_refusal(cmd, toks, variables=None, env=None, cwd=None):
+    """Refuse a segment that is not a simple command the guard can judge:
+    a shell keyword, a runtime-built command name, sudo/doas, a shell with a
+    `-c` cluster, an interpreter reading its program from stdin or from the
+    command line, a program file the run wrote, find -exec, or xargs with a
+    command."""
+    variables = variables or {}
+    raw = _strip_leading_assignments_for_check(tokenize(cmd))
+    if raw and _has_ph(raw[0]):
+        return "a command substitution in command position builds the command name at run time"
+    if raw and "$" in raw[0]:
+        e = expand(raw[0], variables, env)
+        if e is None:
+            return "the command name is built at run time and cannot be judged"
+        raw = [e] + raw[1:]
+    if raw:
+        base = os.path.basename(raw[0])
+        low = base.lower()
+        if low in SHELL_KEYWORDS or base in SHELL_KEYWORDS:
+            return f"{base} is a shell keyword, not a simple command"
+        if low in ("sudo", "doas"):
+            return f"{low} escalates privilege and is refused"
+    stripped = _strip_wrappers(tokenize(cmd))
+    if not stripped:
+        return None
+    if _has_ph(stripped[0]):
+        return "the command name is built at run time and cannot be judged"
+    if "$" in stripped[0]:
+        e = expand(stripped[0], variables, env)
+        if e is None:
+            return "the command name is built at run time and cannot be judged"
+        stripped = [e] + stripped[1:]
+    base = os.path.basename(stripped[0])
+    low = base.lower()
+    if low in SHELL_KEYWORDS or base in SHELL_KEYWORDS:
+        return f"{base} is a shell keyword, not a simple command"
+    if low in ("sudo", "doas"):
+        return f"{low} escalates privilege and is refused"
+    if "/" in stripped[0]:
+        r = _program_refusal("the command", stripped[0], cwd, variables, env)
+        if r:
+            return r
+    for judge in (interpreter_refusal,
+                  awk_refusal if low in AWKS else None,
+                  sed_refusal if low in ("sed", "gsed") else None,
+                  make_refusal if low in ("make", "gmake") else None):
+        if judge:
+            r = judge(stripped, cwd, variables, env)
+            if r:
+                return r
+    if low in ("sort", "gsort", "rg", "grep", "ggrep"):
+        r = _helper_program_refusal(low, stripped[1:], cwd, variables, env)
+        if r:
+            return r
+    if low == "find":
+        for a in stripped[1:]:
+            if a in ("-exec", "-execdir", "-ok", "-okdir"):
+                return "find -exec runs a command the guard cannot see"
+    if low == "xargs":
+        rest = stripped[1:]
+        j = 0
+        while j < len(rest) and rest[j].startswith("-"):
+            j += 1
+        if j < len(rest):
+            return "xargs with a command runs it the guard cannot judge"
+    return None
+
+
+# Options whose value names a helper program a tool runs: sort's external merge
+# compressor, ripgrep's and grep's preprocessor. A file the run wrote there
+# executes.
+HELPER_PROGRAM_OPTS = {
+    "sort": ("--compress-program",),
+    "gsort": ("--compress-program",),
+    "rg": ("--pre",),
+    "grep": (),
+    "ggrep": (),
+}
+
+
+def _helper_program_refusal(low, args, cwd, variables, env):
+    opts = HELPER_PROGRAM_OPTS.get(low, ())
+    i = 0
+    while i < len(args):
+        a = args[i]
+        val = None
+        for opt in opts:
+            if a == opt and i + 1 < len(args):
+                val = args[i + 1]
+                i += 1
+                break
+            if a.startswith(opt + "="):
+                val = a.split("=", 1)[1]
+                break
+        if val is not None:
+            r = _program_refusal(f"{low} {a.split('=', 1)[0]}", val, cwd, variables, env)
+            if r:
+                return r
+        i += 1
+    return None
+
+
+def _strip_leading_assignments_for_check(toks):
+    """Leading VAR=value assignments: refuse a dangerous one, else drop them and
+    return the rest so the command can be judged."""
+    i = 0
+    while i < len(toks) and re.match(r"^[A-Za-z_][A-Za-z0-9_]*=", toks[i]):
+        i += 1
+    return toks[i:]
+
+
+# Environment variables that make a later program run code, load a library,
+# read another config or resolve paths differently.
+BLOCKED_ENV = {
+    "PATH", "CDPATH", "BASH_ENV", "ENV", "PROMPT_COMMAND", "SHELLOPTS", "BASHOPTS", "ZDOTDIR", "IFS",
+    "HOME", "XDG_CONFIG_HOME", "NODE_OPTIONS", "PYTHONPATH", "PYTHONHOME", "PYTHONSTARTUP",
+    "PERL5OPT", "PERL5LIB", "RUBYOPT", "RUBYLIB", "SSH_ASKPASS", "LESSOPEN", "LESSCLOSE",
+    # Proxies redirect every request somewhere the allowlist cannot check.
+    "HTTPS_PROXY", "HTTP_PROXY", "ALL_PROXY", "NO_PROXY",
+    "https_proxy", "http_proxy", "all_proxy", "no_proxy",
+    # These point a fetcher, git or a toolchain at another config, host or CA.
+    "CURL_HOME", "WGETRC", "GH_HOST", "GH_CONFIG_DIR", "BROWSER", "GH_BROWSER",
+    "DEVELOPER_DIR", "TOOLCHAINS", "SDKROOT", "GRADLE_USER_HOME", "JAVA_TOOL_OPTIONS",
+    "NODE_PATH", "NODE_EXTRA_CA_CERTS", "SSL_CERT_FILE", "SSL_CERT_DIR", "CURL_CA_BUNDLE",
+    "REQUESTS_CA_BUNDLE", "PIP_INDEX_URL", "PIP_EXTRA_INDEX_URL", "PIP_CONFIG_FILE",
+    "GEM_HOME", "GEM_PATH", "BUNDLE_GEMFILE",
+}
+BLOCKED_ENV_PREFIXES = ("MULTI_AGENT", "LD_", "DYLD_", "npm_config_", "NPM_CONFIG_", "GH_",
+                        "PYTHON", "GRADLE_", "JAVA_", "MAVEN_")
+# Variables that name a program git or a pager runs; only the no-op values pass.
+PROGRAM_ENV = {"EDITOR", "VISUAL", "PAGER", "MANPAGER", "GIT_EDITOR", "GIT_SEQUENCE_EDITOR", "GIT_PAGER"}
+PROGRAM_ENV_SAFE = {"", "cat", "true", ":", "less"}
+# The GIT_* variables that only label a commit or turn off a prompt. Every
+# other GIT_* is refused: GIT_CONFIG_COUNT/KEY_n/VALUE_n, GIT_CONFIG_GLOBAL,
+# GIT_EXTERNAL_DIFF, GIT_SSH(_COMMAND), GIT_ASKPASS, GIT_EXEC_PATH, GIT_DIR and
+# the rest reconfigure what git runs or where it looks.
+SAFE_GIT_ENV = re.compile(
+    r"^GIT_((AUTHOR|COMMITTER)_(NAME|EMAIL|DATE)|TERMINAL_PROMPT|OPTIONAL_LOCKS|LFS_SKIP_SMUDGE|FLUSH|ADVICE)$")
+
+
+def assignment_refusal(assignment):
+    key, _, value = assignment.partition("=")
+    if key in PROGRAM_ENV:
+        if value.strip("'\"") in PROGRAM_ENV_SAFE:
+            return None
+        return f"setting {key} names a program git or a pager runs"
+    if key in BLOCKED_ENV or key.startswith(BLOCKED_ENV_PREFIXES):
+        return f"setting {key} changes what the run executes or how the guard sees it"
+    if key.startswith("GIT_") and not SAFE_GIT_ENV.match(key):
+        return f"setting {key} reconfigures what git runs or where it looks"
+    return None
+
+
+def dangerous_assignment(toks):
+    assigns, _, refusal = _walk_wrappers(toks)
+    if refusal:
+        return refusal
+    for t in assigns:
+        r = assignment_refusal(t)
+        if r:
+            return r
+    return None
+
+
+# --- policy data --------------------------------------------------------------
+
+def load_policy():
+    for p in POLICY_CANDIDATES:
+        try:
+            with open(p, encoding="utf-8") as f:
+                return json.load(f)
+        except (OSError, ValueError):
+            continue
+    raise RuntimeError("unattended-policy.json not found")
+
+
+def home():
+    return os.path.realpath(os.path.expanduser("~"))
+
+
+def autopilot_root(env=None):
+    env = os.environ if env is None else env
+    root = env.get("MA_AUTOPILOT_ROOT") or os.path.join(home(), ".claude", "autopilot")
+    return os.path.expanduser(root)
+
+
+def unattended_run_root(env=None):
+    env = os.environ if env is None else env
+    return os.path.expanduser(env.get("MA_UNATTENDED_RUN_ROOT") or os.path.join(home(), UNATTENDED_RUN_DIR))
+
+
+def pr_request_path(env=None):
+    env = os.environ if env is None else env
+    sid = env.get("MULTI_AGENT_SESSION_ID", "")
+    if not re.match(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", sid):
+        return None
+    return os.path.join(unattended_run_root(env), PR_REQUESTS_SUBDIR, sid + ".json")
+
+
+def resolve(path, cwd):
+    p = path.strip()
+    p = re.sub(r"^\$\{?HOME\}?(?=/|$)", home(), p)
+    p = os.path.expanduser(p)
+    if not os.path.isabs(p):
+        p = os.path.join(cwd or os.getcwd(), p)
+    return os.path.realpath(os.path.normpath(p))
+
+
+# --- paths --------------------------------------------------------------------
+
+def _under(target, base):
+    """target == base or target is under base, casefolded on darwin."""
+    t, b = _casefold(target), _casefold(base)
+    return t == b or t.startswith(b + os.sep)
+
+
+def check_path(path, cwd, policy, env=None):
+    if not path:
+        return None
+    target = resolve(path, cwd)
+    tcf = _casefold(target)
+    exempt = pr_request_path(env)
+    if exempt and tcf == _casefold(os.path.realpath(exempt)):
+        return None
+    requests = os.path.realpath(os.path.join(unattended_run_root(env), PR_REQUESTS_SUBDIR))
+    if _under(target, requests):
+        return "another session's PR request (or the requests directory itself) is not this run's to write"
+    h = home()
+    # The home directory itself, or an ancestor of it (rm -rf ~, mv ~ /tmp),
+    # contains every host root and credential file below; writing it writes them.
+    if tcf == _casefold(h) or _under(h, target):
+        return "$HOME (or a directory above it) holds every host root and credential the guard protects"
+    ap = os.path.realpath(autopilot_root(env))
+    if _under(target, ap):
+        return "the autopilot runner's own files (queue, config, requests, PR verification) are not the run's to write"
+    for name in policy.get("protectedHomeFiles", []):
+        if tcf == _casefold(os.path.join(h, name)):
+            return f"~/{name} is host configuration"
+    for d in policy.get("protectedHomeDirs", []):
+        if _under(target, os.path.join(h, d)):
+            return f"~/{d}/ is host configuration"
+    # The whole host root is protected, not an enumerated list of entries: an
+    # unattended run writes its logs and PR request under the unattended run
+    # directory (lib/pr-request-location.mjs), never here, so nothing under
+    # ~/.claude, ~/.copilot or ~/.codex is the run's to write.
+    for root in policy.get("protectedHostRoots", []):
+        base = os.path.join(h, root)
+        if tcf == _casefold(base) or tcf.startswith(_casefold(base) + os.sep):
+            return f"~/{root}/ is host configuration and the installed pipeline; an unattended run writes under ~/{UNATTENDED_RUN_DIR}"
+    segs = target.split(os.sep)
+    segs_cf = [_casefold(s) for s in segs]
+    repo = policy.get("protectedRepoPaths", {})
+    for d in repo.get("dirs", []):
+        parts = [_casefold(p) for p in d.split("/")]
+        for i in range(len(segs_cf) - len(parts) + 1):
+            if segs_cf[i:i + len(parts)] == parts:
+                return f"{d}/ is protected: workflows, hooks and agent config change what runs next"
+        # A directory target that is an ancestor of a protected path (mv evil .github).
+        for k in range(1, len(parts)):
+            if segs_cf[-k:] == parts[:k]:
+                return f"{'/'.join(d.split('/')[:k])} is protected: it holds {d}/"
+    name = segs[-1]
+    ncf = _casefold(name)
+    if any(ncf == _casefold(f) for f in repo.get("files", [])):
+        return f"{name} is protected"
+    man = policy.get("manifests", {})
+    if any(ncf == _casefold(f) for f in man.get("files", [])) or any(re.search(rx, name) for rx in man.get("patterns", [])):
+        return f"{name} is a dependency manifest or lockfile; adding a package is a person's decision"
+    return None
+
+
+def _short_cluster_has(tok, ch):
+    return tok.startswith("-") and not tok.startswith("--") and ch in tok[1:]
+
+
+# Options of cp/mv/rsync/install/ditto whose next token is a VALUE, not a path.
+COPY_VALUE_OPTS = {
+    "cp": set(),
+    "ln": set(),
+    "install": {"-m", "-o", "-g", "-B", "-S"},
+    "ditto": {"--rsrc", "--arch", "--bom"},
+    "mv": set(),
+    "rsync": {"--exclude", "--include", "--exclude-from", "--include-from", "--files-from",
+              "-e", "--rsh", "--chmod", "--chown", "--rsync-path", "--compress-level",
+              "--filter", "-f", "--out-format", "--log-file", "--bwlimit", "--timeout",
+              "--partial-dir", "--backup-dir", "--suffix", "--max-size", "--min-size",
+              "--block-size", "-B", "--modify-window", "-T", "--temp-dir", "--link-dest",
+              "--copy-dest", "--compare-dest", "--port", "--sockopts"},
+}
+
+
+def _copy_operands(cmd, args):
+    """The positional path operands of a copy-like command, with option values
+    consumed so `rsync --exclude X src dst` does not treat X as a path."""
+    value_opts = COPY_VALUE_OPTS.get(cmd, set())
+    out, i = [], 0
+    while i < len(args):
+        a = args[i]
+        if a == "--":
+            out.extend(args[i + 1:])
+            break
+        if a.startswith("-") and a != "-":
+            key = a.split("=", 1)[0]
+            if key in value_opts and "=" not in a:
+                i += 2
+                continue
+            i += 1
+            continue
+        out.append(a)
+        i += 1
+    return out
+
+
+def _is_dir_dest(cmd, args, dest):
+    """A copy into a directory names files inside it by their source basenames.
+    Recursive (cp -R, rsync -a, ditto) or an existing directory destination, or
+    a destination written with a trailing slash."""
+    if dest.endswith("/"):
+        return True
+    recursive = any(
+        _short_cluster_has(a, "R") or _short_cluster_has(a, "r") or _short_cluster_has(a, "a")
+        or a in ("--recursive", "--archive")
+        for a in args
+    )
+    d = os.path.expanduser(re.sub(r"^\$\{?HOME\}?(?=/|$)", home(), dest.strip("'\"")))
+    if recursive or cmd == "rsync" or cmd == "ditto":
+        return True
+    try:
+        return os.path.isdir(d)
+    except OSError:
+        return False
+
+
+def dest_write_targets(cmd, args, sources, dest):
+    """The paths a copy writes: the destination, plus, when it is a directory,
+    the destination joined with each source's basename (cp -R dir ~/ writes
+    ~/dir)."""
+    out = [dest]
+    if _is_dir_dest(cmd, args, dest):
+        for src in sources:
+            name = os.path.basename(src.rstrip("/"))
+            if name:
+                out.append(dest.rstrip("/") + "/" + name)
+    return out
+
+
+def write_targets(toks):
+    """Files a simple shell command writes."""
+    if not toks:
+        return []
+    cmd = os.path.basename(toks[0]).lower()
+    args = toks[1:]
+    plain = [a for a in args if not a.startswith("-")]
+    if cmd == "tee":
+        return plain
+    if cmd in ("sed", "gsed"):
+        inplace = any(a == "-i" or a.startswith("-i") or a.startswith("--in-place") or _short_cluster_has(a, "i") for a in args)
+        return plain[1:] if inplace and len(plain) >= 2 else []
+    if cmd == "perl":
+        if not any(_short_cluster_has(a, "i") or a.startswith("-i") for a in args):
+            return []
+        files, skip = [], False
+        for a in args:
+            if skip:
+                skip = False
+                continue
+            if a in ("-e", "-E"):
+                skip = True
+                continue
+            if a.startswith("-"):
+                continue
+            files.append(a)
+        return files
+    if cmd in ("cp", "mv", "ln", "install", "rsync", "ditto"):
+        operands = _copy_operands(cmd, args)
+        for i, a in enumerate(args):
+            if a in ("-t", "--target-directory") and i + 1 < len(args):
+                return [args[i + 1]]
+            if a.startswith("--target-directory="):
+                return [a.split("=", 1)[1]]
+            if a.startswith("-t") and len(a) > 2 and not a.startswith("--"):
+                return [a[2:]]
+        if cmd == "ln":
+            return operands
+        if len(operands) < 2:
+            return []
+        sources, dest = operands[:-1], operands[-1]
+        out = list(dest_write_targets(cmd, args, sources, dest))
+        # mv removes its sources; rsync with --remove-source-files does too.
+        if cmd == "mv" or (cmd == "rsync" and any(a == "--remove-source-files" for a in args)):
+            out.extend(sources)
+        return out
+    if cmd in ("rm", "unlink", "shred"):
+        # rm removes what it names: the paths are writes, and a home entry named
+        # as an ancestor (rm -rf ~) is a write to everything under it.
+        return plain
+    if cmd in ("touch", "truncate", "mkdir", "rmdir", "mkfifo", "mknod", "mktemp"):
+        return plain
+    if cmd in ("chflags", "xattr"):
+        # Metadata changes to a protected file are refused the same as a write.
+        return plain[1:] if len(plain) >= 2 else plain
+    if cmd in ("chmod", "chown"):
+        return plain[1:]
+    if cmd == "dd":
+        return [a[3:] for a in args if a.startswith("of=")]
+    if cmd in ("sort", "gsort"):
+        out = []
+        for i, a in enumerate(args):
+            if a in ("-o", "--output") and i + 1 < len(args):
+                out.append(args[i + 1])
+            elif a.startswith("--output="):
+                out.append(a.split("=", 1)[1])
+            elif a.startswith("-o") and len(a) > 2 and not a.startswith("--"):
+                out.append(a[2:])
+        return out
+    if cmd in ("find", "gfind"):
+        out = []
+        for i, a in enumerate(args):
+            if a in ("-fprint", "-fprint0", "-fprintf", "-fls") and i + 1 < len(args):
+                out.append(args[i + 1])
+        if "-delete" in args:
+            for a in args:
+                if a.startswith("-") or a in ("(", "!"):
+                    break
+                out.append(a)
+        return out
+    return []
+
+
+def _opt_value(args, i, names):
+    """Value of args[i] when it is one of names: `--opt value`, `--opt=value`,
+    or `-oVALUE` attached. Returns (value, consumed) or (None, 1)."""
+    a = args[i]
+    for n in names:
+        if a == n:
+            return (args[i + 1] if i + 1 < len(args) else None), 2
+        if n.startswith("--") and a.startswith(n + "="):
+            return a.split("=", 1)[1], 1
+        if not n.startswith("--") and len(n) == 2 and a.startswith(n) and len(a) > 2 and not a.startswith("--"):
+            return a[2:], 1
+    return None, 1
+
+
+def extractor_write_targets(toks):
+    """Write destinations of curl -o, tar -C, unzip -d, git checkout -- / restore,
+    patch -o - the tools whose write target is an option value, not a positional."""
+    if not toks:
+        return []
+    base = os.path.basename(toks[0]).lower()
+    args = toks[1:]
+    out = []
+    if base == "curl":
+        i = 0
+        while i < len(args):
+            v, step = _opt_value(args, i, ("-o", "--output", "--output-dir"))
+            if v is not None and (args[i] in ("-o", "--output", "--output-dir") or args[i].startswith("--output") or (args[i].startswith("-o") and len(args[i]) > 2)):
+                out.append(v)
+            i += step
+        return out
+    if base in ("tar", "gtar", "bsdtar"):
+        i = 0
+        while i < len(args):
+            v, step = _opt_value(args, i, ("-C", "--directory"))
+            if v is not None and (args[i] in ("-C", "--directory") or args[i].startswith("--directory=") or (args[i].startswith("-C") and len(args[i]) > 2)):
+                out.append(v)
+            i += step
+        return out
+    if base == "unzip":
+        for i, a in enumerate(args):
+            if a == "-d" and i + 1 < len(args):
+                out.append(args[i + 1])
+            elif a.startswith("-d") and len(a) > 2:
+                out.append(a[2:])
+        return out
+    if base in ("7z", "7za", "7zr"):
+        for a in args:
+            if a.startswith("-o") and len(a) > 2:
+                out.append(a[2:])
+        return out
+    if base in ("diff", "gdiff"):
+        for a in args:
+            if a.startswith("--to-file="):
+                out.append(a.split("=", 1)[1])
+        return out
+    if base == "xcodebuild":
+        opts = ("-derivedDataPath", "-resultBundlePath", "-exportPath", "-archivePath")
+        i = 0
+        while i < len(args):
+            if args[i] in opts and i + 1 < len(args):
+                out.append(args[i + 1])
+                i += 2
+                continue
+            i += 1
+        return out
+    if base == "swift":
+        opts = ("--scratch-path", "--build-path", "--cache-path", "--package-path")
+        i = 0
+        while i < len(args):
+            a = args[i]
+            for o in opts:
+                if a == o and i + 1 < len(args):
+                    out.append(args[i + 1])
+                    i += 1
+                elif a.startswith(o + "="):
+                    out.append(a.split("=", 1)[1])
+            i += 1
+        return out
+    if base == "patch":
+        for i, a in enumerate(args):
+            if a in ("-o", "--output") and i + 1 < len(args):
+                out.append(args[i + 1])
+            elif a.startswith("--output="):
+                out.append(a.split("=", 1)[1])
+        plain = [a for a in args if not a.startswith("-")]
+        out.extend(plain)
+        return out
+    if base == "git":
+        sub, rest = _git_sub(toks)
+        plain = [a for a in rest if not a.startswith("-")]
+        if sub == "restore":
+            return plain
+        if sub == "checkout" and "--" in rest:
+            k = rest.index("--")
+            return [a for a in rest[k + 1:] if not a.startswith("-")]
+        # checkout <ref> <path...>: everything after the first plain (the ref).
+        if sub == "checkout" and len(plain) >= 2:
+            out.extend(plain[1:])
+        if sub == "mv" and len(plain) >= 2:
+            out.append(plain[-1])
+        # clone / init / worktree add write into a destination directory the run
+        # would then own; refusing a protected destination stops seeding .claude.
+        if sub == "clone" and len(plain) >= 2:
+            out.append(plain[-1])
+        if sub == "init" and plain:
+            out.append(plain[-1])
+        if sub == "worktree" and len(plain) >= 2 and plain[0] == "add":
+            out.append(plain[1])
+        if sub == "read-tree" and "--prefix" in " ".join(rest):
+            for a in rest:
+                if a.startswith("--prefix="):
+                    out.append(a.split("=", 1)[1])
+        if sub == "checkout-index":
+            for a in rest:
+                if a.startswith("--prefix="):
+                    out.append(a.split("=", 1)[1])
+                elif a == "--prefix":
+                    j = rest.index(a)
+                    if j + 1 < len(rest):
+                        out.append(rest[j + 1])
+        if sub in ("apply", "am"):
+            for a in rest:
+                if a.startswith("--directory="):
+                    out.append(a.split("=", 1)[1])
+                elif a == "--directory":
+                    j = rest.index(a)
+                    if j + 1 < len(rest):
+                        out.append(rest[j + 1])
+        if sub in ("archive", "bundle"):
+            for a in rest:
+                if a.startswith("--output="):
+                    out.append(a.split("=", 1)[1])
+                elif a in ("-o", "--output"):
+                    j = rest.index(a)
+                    if j + 1 < len(rest):
+                        out.append(rest[j + 1])
+            if sub == "bundle" and plain and plain[0] == "create" and len(plain) >= 2:
+                out.append(plain[1])
+        names = ("--output", "--output-directory") + (("-o",) if sub == "format-patch" else ())
+        i = 0
+        while i < len(rest):
+            v, step = _opt_value(rest, i, names)
+            if v is not None:
+                out.append(v)
+            i += step
+        return out
+    return []
+
+
+# --- commands -----------------------------------------------------------------
+
+def _git_sub(toks):
+    """The git subcommand and its remaining args, skipping git's global options.
+    Refusal of dangerous `-c` values is handled by git_config_refusal."""
+    i = 1
+    while i < len(toks):
+        t = toks[i]
+        if t in ("-C", "-c", "--git-dir", "--work-tree", "--exec-path", "--namespace"):
+            i += 2
+        elif t.startswith("-"):
+            i += 1
+        else:
+            return t.lower(), toks[i + 1:]
+    return "", []
+
+
+# Config keys that make git run a program, load more config, or send somewhere
+# else. One list for `git -c`, `git --config-env`, `git clone -c` and
+# `git config`.
+GIT_EXEC_CONFIG = re.compile(
+    r"^(alias\..*"
+    r"|core\.(hookspath|sshcommand|fsmonitor|editor|pager|askpass|gitproxy|alternaterefscommand|worktree|attributesfile|excludesfile)"
+    r"|sequence\.editor|diff\.external|diff\..*\.(command|textconv)|difftool\..*|mergetool\..*|merge\..*\.driver"
+    r"|filter\..*|credential\..*|gpg\..*|url\..*\.(insteadof|pushinsteadof)|include\..*|includeif\..*"
+    r"|http\..*|remote\..*|branch\..*\.(remote|pushremote)|protocol\..*|pager\..*|interactive\.difffilter"
+    r"|uploadpack\..*|receive\..*|ssh\.variant|init\.templatedir|submodule\..*|trailer\..*|hook\..*"
+    r"|man\..*|browser\..*|web\.browser|instaweb\..*|sendemail\..*|safe\.directory|color\.pager)$",
+    re.I,
+)
+
+
+def _git_exec_key(val):
+    key = val.split("=", 1)[0]
+    return key if GIT_EXEC_CONFIG.match(key) else None
+
+
+def git_config_refusal(toks):
+    """git -c KEY=VALUE / --config-env=KEY=ENV with a key that runs a program
+    or redirects git, before the subcommand."""
+    i = 1
+    while i < len(toks):
+        t = toks[i]
+        val = None
+        if t == "-c" and i + 1 < len(toks):
+            val = toks[i + 1]
+            i += 2
+        elif t.startswith("-c") and len(t) > 2:
+            val = t[2:]
+            i += 1
+        elif t == "--config-env" and i + 1 < len(toks):
+            val = toks[i + 1]
+            i += 2
+        elif t.startswith("--config-env="):
+            val = t.split("=", 1)[1]
+            i += 1
+        else:
+            if t.startswith("-"):
+                i += 1
+                if t in ("-C", "--git-dir", "--work-tree", "--exec-path", "--namespace"):
+                    i += 1
+                continue
+            break
+        if val is None:
+            continue
+        key = _git_exec_key(val)
+        if key:
+            return f"git -c {key} reconfigures git for the whole run"
+    return None
+
+
+GIT_CONFIG_READS = {"--get", "--get-all", "--get-regexp", "--get-urlmatch", "--list", "-l", "--show-origin",
+                    "--show-scope", "--name-only", "get", "list"}
+GIT_CONFIG_WRITE_SUBS = {"set", "unset", "rename-section", "remove-section"}
+GIT_CONFIG_WRITE_OPTS = {"--unset", "--unset-all", "--add", "--replace-all", "--rename-section", "--remove-section"}
+
+
+def _git_config(rest):
+    if any(a in ("-e", "--edit", "edit") for a in rest):
+        return "git config --edit opens an editor on the config"
+    if any(a in GIT_CONFIG_READS for a in rest):
+        return None
+    keys = [a for a in rest if not a.startswith("-")]
+    writes = bool(keys and keys[0] in GIT_CONFIG_WRITE_SUBS)
+    if writes:
+        keys = keys[1:]
+    writes = writes or len(keys) >= 2 or any(a in GIT_CONFIG_WRITE_OPTS for a in rest)
+    if not writes:
+        return None
+    if any(a in ("--global", "--system") for a in rest):
+        return "git config --global / --system writes this machine's git configuration"
+    for k in keys[:2]:
+        if GIT_EXEC_CONFIG.match(k):
+            return f"git config {k} changes what git runs or where it sends"
+    return None
+
+
+# git subcommands that write to a remote or another version-control system.
+GIT_OUTWARD_SUBS = {
+    "send-pack": "git send-pack writes to a remote",
+    "http-push": "git http-push writes to a remote",
+    "upload-archive": "git upload-archive serves this repository to a remote",
+    "svn": "git svn writes to a Subversion remote",
+    "p4": "git p4 writes to a Perforce remote",
+    "imap-send": "git imap-send sends mail",
+    "request-pull": "git request-pull is a publish step",
+    "web--browse": "git web--browse opens a browser on a URL",
+    "instaweb": "git instaweb starts a web server and opens a browser",
+    "daemon": "git daemon serves this repository to the network",
+}
+# Global flags before the subcommand that move where git reads or writes, or
+# what it runs. --git-dir / --work-tree / --exec-path / --namespace are refused;
+# -C and -c are handled elsewhere (-c by git_config_refusal).
+GIT_GLOBAL_REFUSED = ("--git-dir", "--work-tree", "--exec-path", "--namespace")
+
+
+def git_global_flag_refusal(toks):
+    """A git global flag before the subcommand that redirects git's directories
+    or its helper path."""
+    for t in toks[1:]:
+        if not t.startswith("-"):
+            break
+        key = t.split("=", 1)[0]
+        if key in GIT_GLOBAL_REFUSED:
+            return f"git {key} redirects where git reads, writes or finds its programs"
+    return None
+
+
+def git_credential_refusal(sub, rest):
+    """git credential / credential-<helper>: reading or writing the store."""
+    if sub == "credential" or sub.startswith("credential-"):
+        return f"git {sub} reads or writes the credential store"
+    if sub == "lfs" and rest and rest[0] == "push":
+        return "git lfs push writes to a remote"
+    return None
+
+
+def git_exec_refusal(sub, rest, toks):
+    """git subcommands and options that run a command line or a transport the
+    guard cannot see."""
+    if any(t.startswith(("ext::", "fd::")) for t in toks):
+        return "an ext:: or fd:: git transport runs a command"
+    if sub in GIT_OUTWARD_SUBS:
+        return GIT_OUTWARD_SUBS[sub]
+    r = git_credential_refusal(sub, rest)
+    if r:
+        return r
+    if sub == "rebase":
+        for a in rest:
+            if a in ("--exec", "-x") or a.startswith("--exec=") or _short_cluster_has(a, "x"):
+                return "git rebase --exec runs a command after each commit"
+    if sub == "bisect" and rest and rest[0] == "run":
+        return "git bisect run runs a command"
+    if sub == "submodule" and "foreach" in rest:
+        return "git submodule foreach runs a command in each submodule"
+    if sub == "difftool":
+        for a in rest:
+            if a in ("-x", "--extcmd") or a.startswith("--extcmd=") or _short_cluster_has(a, "x"):
+                return "git difftool --extcmd runs a command"
+    if sub in ("filter-branch", "filter-repo"):
+        return f"git {sub} runs filter commands"
+    if sub == "grep":
+        for a in rest:
+            if a.startswith("-O") or a.startswith("--open-files-in-pager"):
+                return "git grep -O runs a pager command"
+    if sub == "maintenance" and rest and rest[0] in ("start", "register"):
+        return f"git maintenance {rest[0]} installs a background job that runs git"
+    if sub == "help" and any(a in ("-w", "--web") for a in rest):
+        return "git help -w opens a browser"
+    for a in rest:
+        key = a.split("=", 1)[0]
+        if key in ("--upload-pack", "--receive-pack", "--exec", "--template") or (sub == "clone" and a == "-u"):
+            return f"git {sub} {key} runs a program or installs hooks"
+    if sub == "clone":
+        for i, a in enumerate(rest):
+            val = None
+            if a in ("-c", "--config") and i + 1 < len(rest):
+                val = rest[i + 1]
+            elif a.startswith("--config="):
+                val = a.split("=", 1)[1]
+            if val and _git_exec_key(val):
+                return f"git clone -c {_git_exec_key(val)} reconfigures the new repository"
+    return None
+
+
+# git subcommands that reach a remote host: the URL argument (or the configured
+# remote) must be on the allowlist, the same rule curl and gh follow.
+GIT_NETWORK_SUBS = {"fetch", "clone", "pull", "ls-remote", "archive", "bundle", "remote-https", "remote-http"}
+
+
+def git_url_refusal(sub, rest, toks, policy, env):
+    """A git subcommand that contacts a remote, checked against the network
+    allowlist. A literal URL argument is host-checked; a bare remote name or no
+    argument (fetch origin, pull) is left to the configured remote, which the
+    guard does not resolve, so it passes here and the sandbox confines it."""
+    urls = []
+    if sub in GIT_NETWORK_SUBS:
+        for a in rest:
+            if "://" in a or a.startswith("git@") or re.match(r"^[a-z]+::", a):
+                urls.append(a)
+    if sub == "submodule" and rest and rest[0] == "add":
+        for a in rest[1:]:
+            if "://" in a or a.startswith("git@"):
+                urls.append(a)
+    if sub == "remote" and rest and rest[0] in ("add", "set-url"):
+        for a in rest[1:]:
+            if "://" in a or a.startswith("git@"):
+                urls.append(a)
+    for a in rest:
+        if a.startswith("--remote="):
+            v = a.split("=", 1)[1]
+            if "://" in v or v.startswith("git@"):
+                urls.append(v)
+    for u in urls:
+        if u.startswith("git@") or re.match(r"^[a-z]+::", u):
+            return f"git {sub} over ssh or a custom transport ({u[:40]}) cannot be host-checked; refused unattended"
+        r = check_url_host(u, policy, env, f"git {sub}")
+        if r:
+            return r
+    return None
+
+
+GH_WRITES = {
+    "pr": {"create", "merge", "ready", "edit", "comment", "review", "close", "reopen", "lock", "unlock"},
+    "issue": {"create", "close", "edit", "comment", "reopen", "delete", "transfer", "lock", "unlock", "pin", "unpin", "develop"},
+    "release": {"create", "edit", "delete", "upload", "delete-asset"},
+    "repo": {"create", "edit", "delete", "fork", "rename", "archive", "unarchive", "sync", "deploy-key", "set-default"},
+    "workflow": {"run", "enable", "disable"},
+    "run": {"rerun", "cancel", "delete"},
+    "label": {"create", "edit", "delete", "clone"},
+    "gist": {"create", "edit", "delete", "clone"},
+    "secret": None,
+    "variable": None,
+    "ruleset": None,
+    "alias": None,
+    "ssh-key": None,
+    "gpg-key": None,
+    "extension": None,
+    "codespace": None,
+    "cache": {"delete"},
+    "project": {"create", "edit", "delete", "close", "copy", "field-create", "field-delete", "item-add", "item-archive", "item-create", "item-delete", "item-edit", "link", "unlink", "mark-template"},
+}
+GH_API_FIELD_FLAGS = {"-f", "-F", "--field", "--raw-field", "--input"}
+
+
+def _is_field_flag(t):
+    if t in GH_API_FIELD_FLAGS:
+        return True
+    if any(t.startswith(f + "=") for f in GH_API_FIELD_FLAGS if f.startswith("--")):
+        return True
+    # attached short forms: -ftitle=x, -Fbody=@f
+    return bool(re.match(r"^-[fF].", t))
+
+
+# gh's built-in command aliases, so `gh cs` is judged as `gh codespace`.
+GH_ALIASES = {
+    "cs": "codespace", "rs": "release", "ext": "extension", "co": "pr",
+    "pr": "pr", "i": "issue", "r": "repo", "w": "workflow",
+}
+# gh config keys that hold or point at a credential; reading one prints a secret.
+GH_TOKEN_KEYS = {"oauth_token", "token"}
+
+
+def _gh(toks, policy=None, env=None):
+    args = toks[1:]
+    # Capture -R/--repo (dropped) and --hostname (dropped from the verb scan but
+    # host-checked). A --hostname off the allowlist is an exfiltration target.
+    cleaned, hostname, i = [], None, 0
+    while i < len(args):
+        a = args[i]
+        if a in ("-R", "--repo"):
+            i += 2
+            continue
+        if a.startswith("--repo="):
+            i += 1
+            continue
+        if a == "--hostname" and i + 1 < len(args):
+            hostname = args[i + 1]
+            i += 2
+            continue
+        if a.startswith("--hostname="):
+            hostname = a.split("=", 1)[1]
+            i += 1
+            continue
+        cleaned.append(a)
+        i += 1
+    if hostname and policy is not None:
+        r = check_url_host(hostname, policy, env, "gh --hostname")
+        if r:
+            return r
+    plains = [a for a in cleaned if not a.startswith("-")]
+    if not plains:
+        return None
+    group = GH_ALIASES.get(plains[0], plains[0])
+    if group == "api":
+        return _gh_api(cleaned[cleaned.index(plains[0]) + 1:], policy, env)
+    if group == "auth":
+        sub = plains[1] if len(plains) > 1 else ""
+        if sub == "token" or "--show-token" in cleaned or "-t" in cleaned:
+            return "gh auth token prints a credential"
+        if sub == "status":
+            return None
+        return f"gh auth {sub}".rstrip() + " reads or changes this machine's GitHub credentials"
+    if group == "config":
+        sub = plains[1] if len(plains) > 1 else ""
+        if sub == "set":
+            return "gh config set changes the GitHub CLI's configuration"
+        if sub == "get":
+            if any(k in GH_TOKEN_KEYS for k in plains[2:]):
+                return "gh config get of a token prints a credential"
+        return None
+    if group not in GH_WRITES:
+        return None
+    verbs = GH_WRITES[group]
+    sub = plains[1] if len(plains) > 1 else ""
+    if verbs is None or sub in verbs:
+        return f"gh {group} {sub}".strip() + " writes to GitHub; the runner is the only writer"
+    return None
+
+
+def _gh_api(rest, policy=None, env=None):
+    method = "GET"
+    fields = False
+    endpoint = ""
+    field_values = []
+    i = 0
+    while i < len(rest):
+        t = rest[i]
+        if t in ("-X", "--method"):
+            method = (rest[i + 1] if i + 1 < len(rest) else "").upper()
+            i += 2
+            continue
+        if t.startswith("--method="):
+            method = t.split("=", 1)[1].upper()
+        elif t.startswith("-X") and len(t) > 2:
+            method = t[2:].upper()
+        elif _is_field_flag(t):
+            fields = True
+            if t in GH_API_FIELD_FLAGS:
+                if i + 1 < len(rest):
+                    field_values.append(rest[i + 1])
+                i += 2
+                continue
+            field_values.append(t.split("=", 1)[1] if "=" in t else t[2:])
+        elif not t.startswith("-") and not endpoint:
+            endpoint = t
+        i += 1
+    # An endpoint given as a full URL goes to whatever host it names, not
+    # api.github.com; host-check it.
+    if "://" in endpoint and policy is not None:
+        r = check_url_host(endpoint, policy, env, "gh api")
+        if r:
+            return r
+    if endpoint == "graphql":
+        joined = " ".join(rest).lower()
+        if any(v.startswith("@") or "=@" in v for v in field_values):
+            return "gh api graphql with an @file field reads a file into the mutation the guard cannot see"
+        if re.search(r"\bmutation\b", joined) or "--input" in rest:
+            return "gh api graphql mutation writes to GitHub"
+        return None
+    explicit = any(t in ("-X", "--method") or t.startswith("--method=") or (t.startswith("-X") and len(t) > 2) for t in rest)
+    if method not in ("GET", "HEAD") or (fields and not explicit):
+        return f"gh api with method {method if explicit else 'POST (fields imply it)'} writes to GitHub"
+    return None
+
+
+CURL_VALUE_FLAGS = {"-o", "--output", "-H", "--header", "-u", "--user", "-A", "--user-agent", "-e", "--referer",
+                    "-X", "--request", "-m", "--max-time", "--connect-timeout", "-w", "--write-out", "-K", "--config",
+                    "-x", "--proxy", "-b", "--cookie", "-c", "--cookie-jar", "--retry", "-r", "--range", "--cacert",
+                    "--cert", "--key", "-E", "--resolve", "--connect-to", "-O", "--output-dir", "--limit-rate", "-Y", "-y",
+                    "--unix-socket", "--doh-url"}
+CURL_REFUSED_FLAGS = {"-x", "--proxy", "--connect-to", "--resolve", "-K", "--config", "--unix-socket", "--doh-url"}
+WGET_WRITE_FLAGS = {"--post-data", "--post-file", "--body-data", "--body-file", "--method"}
+CURL_BODY_LONG = {"--data", "--data-raw", "--data-binary", "--data-urlencode", "--data-ascii", "--json", "--form", "--form-string", "--upload-file"}
+
+
+def _fetch(toks, policy, env=None):
+    tool = os.path.basename(toks[0]).lower()
+    args = toks[1:]
+    if tool == "curl":
+        method = "GET"
+        for a in args:
+            if a in CURL_REFUSED_FLAGS or a.split("=", 1)[0] in CURL_REFUSED_FLAGS:
+                return f"curl {a.split('=', 1)[0]} redirects the connection somewhere the allowlist cannot check"
+        for i, t in enumerate(args):
+            if t in ("-X", "--request") and i + 1 < len(args):
+                method = args[i + 1].upper()
+            elif t.startswith("-X") and len(t) > 2 and not t.startswith("--"):
+                method = t[2:].upper()
+            elif t.startswith("--request="):
+                method = t.split("=", 1)[1].upper()
+            body = t in CURL_BODY_LONG or any(t.startswith(f + "=") for f in CURL_BODY_LONG)
+            if not body and t.startswith("-") and not t.startswith("--"):
+                # short cluster: -d, -F, -T, and attached forms -d@file, -Tfile
+                if any(ch in t[1:] for ch in ("d", "F", "T")):
+                    body = True
+            if body:
+                return "curl with a request body or upload writes to a remote service; the runner is the only writer"
+        if method not in ("GET", "HEAD"):
+            return f"curl -X {method} writes to a remote service; the runner is the only writer"
+        urls, skip = [], False
+        for i, t in enumerate(args):
+            if skip:
+                skip = False
+                continue
+            if t == "--url" and i + 1 < len(args):
+                urls.append(args[i + 1])
+                skip = True
+                continue
+            if t in CURL_VALUE_FLAGS:
+                skip = True
+                continue
+            if not t.startswith("-"):
+                urls.append(t)
+    else:
+        if any(t in WGET_WRITE_FLAGS or t.split("=", 1)[0] in WGET_WRITE_FLAGS for t in args):
+            return "wget with a request body writes to a remote service; the runner is the only writer"
+        urls = [t for t in args if not t.startswith("-")]
+    if not urls:
+        return f"{tool} with no literal URL: the host cannot be checked against the allowlist"
+    for u in urls:
+        r = check_url_host(u, policy, env, tool)
+        if r:
+            return r
+    return None
+
+
+def _hosts(policy, env=None):
+    hosts = set(h.lower() for h in policy.get("network", {}).get("staticHosts", []))
+    env = os.environ if env is None else env
+    snap = env.get("MA_UNATTENDED_HOSTS")
+    if snap:
+        for h in snap.split(","):
+            if h.strip():
+                hosts.add(h.strip().lower())
+        return hosts
+    prefs = env.get("MULTI_AGENT_PREFS") or os.path.join(home(), ".claude", "multi-agent-preferences.json")
+    try:
+        with open(prefs, encoding="utf-8") as f:
+            configured = ((json.load(f).get("global") or {}).get("hosts") or {})
+        for key in policy.get("network", {}).get("prefsHostKeys", []):
+            v = configured.get(key)
+            if isinstance(v, str) and v.strip():
+                hosts.add(re.sub(r"^[a-z]+://", "", v.strip().lower()).split("/")[0].split(":")[0])
+    except (OSError, ValueError, AttributeError):
+        pass
+    return hosts
+
+
+def _host_of(url):
+    if "$" in url or "`" in url:
+        return None
+    try:
+        parts = urlsplit(url if "://" in url else "//" + url, scheme="https")
+    except ValueError:
+        return None
+    host = parts.hostname
+    return host.lower() if host else None
+
+
+def _allowed_host(host, allowed):
+    return any(host == a or host.endswith("." + a) for a in allowed)
+
+
+def check_url_host(url, policy, env=None, tool="fetch"):
+    if "$" in url or "`" in url:
+        return f"{tool} to a URL built at run time: the host cannot be checked against the allowlist"
+    host = _host_of(url)
+    if not host:
+        return f"{tool} target '{url[:60]}' is not a URL the allowlist can check"
+    if not _allowed_host(host, _hosts(policy, env)):
+        return f"{tool} to {host}: not in the unattended network allowlist (unattended-policy.json + prefs.global.hosts)"
+    return None
+
+
+# Tools that open a connection to a host the allowlist cannot check (an
+# arbitrary host, a raw socket, a name lookup that can carry data in the query).
+# Refused outright unattended; documented as residual in unattended-security.md.
+NETWORK_TOOLS = {
+    "ssh": "ssh opens a connection to an arbitrary host and can run a command there",
+    "scp": "scp copies over ssh to an arbitrary host",
+    "sftp": "sftp transfers over ssh to an arbitrary host",
+    "rsh": "rsh runs a command on a remote host",
+    "telnet": "telnet opens a raw connection to an arbitrary host",
+    "nc": "nc opens a raw socket the allowlist cannot check",
+    "ncat": "ncat opens a raw socket the allowlist cannot check",
+    "netcat": "netcat opens a raw socket the allowlist cannot check",
+    "socat": "socat opens a raw socket the allowlist cannot check",
+    "dig": "dig resolves a name and can carry data in the query",
+    "nslookup": "nslookup resolves a name and can carry data in the query",
+    "host": "host resolves a name and can carry data in the query",
+    "drill": "drill resolves a name and can carry data in the query",
+    "ping": "ping reaches an arbitrary host",
+    "ping6": "ping6 reaches an arbitrary host",
+    "aria2c": "aria2c downloads from an arbitrary host",
+    "http": "httpie reaches an arbitrary host",
+    "https": "httpie reaches an arbitrary host",
+    "httpie": "httpie reaches an arbitrary host",
+    "xh": "xh reaches an arbitrary host",
+}
+
+
+def network_tool_refusal(base):
+    return NETWORK_TOOLS.get(base)
+
+
+# --- installs -----------------------------------------------------------------
+
+_GIT_CACHE = {}
+
+
+def _changed_files(cwd):
+    key = os.path.realpath(cwd or ".")
+    if key in _GIT_CACHE:
+        return _GIT_CACHE[key]
+    try:
+        import subprocess
+
+        out = subprocess.run(["git", "-C", key, "diff", "--name-only", "HEAD"],
+                             capture_output=True, text=True, timeout=3)
+        val = None if out.returncode != 0 else {os.path.basename(l.strip()) for l in out.stdout.splitlines() if l.strip()}
+    except Exception:
+        val = None
+    _GIT_CACHE[key] = val
+    return val
+
+
+def _manifest_changed(names, cwd):
+    changed = _changed_files(cwd)
+    if changed is None:
+        return True
+    return bool(changed & set(names))
+
+
+NODE_LOCKS = ["package.json", "package-lock.json", "npm-shrinkwrap.json", "yarn.lock", "pnpm-lock.yaml", "bun.lock", "bun.lockb"]
+
+
+def _local_bin(name, cwd):
+    """node_modules/.bin/<name> in cwd or an ancestor, the way npx looks."""
+    d = os.path.realpath(cwd or ".")
+    while True:
+        if os.path.exists(os.path.join(d, "node_modules", ".bin", name)):
+            return True
+        parent = os.path.dirname(d)
+        if parent == d:
+            return False
+        d = parent
+
+
+def _npx(tool, args, cwd):
+    """npx / npm exec run a binary; when it is not already installed they
+    fetch the package, and with no TTY they do it without asking. Only a
+    binary present in node_modules/.bin passes."""
+    spec = ""
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a in ("-y", "--yes") or a.startswith("--package") or a == "-p":
+            return f"{tool} --yes / --package fetches a package that is not in the lockfile"
+        if a in ("-c", "--call") or a.startswith("--call="):
+            return f"{tool} --call runs a shell command the guard cannot see"
+        if a == "--":
+            spec = args[i + 1] if i + 1 < len(args) else ""
+            break
+        if not a.startswith("-"):
+            spec = a
+            break
+        i += 1
+    if not spec:
+        return None
+    name = spec[1:] if spec.startswith("@") else spec
+    if "@" in name or ":" in name or name.startswith((".", "/")) and not spec.startswith("@"):
+        return f"{tool} {spec[:40]} names a version, path or URL: it fetches or runs a package outside node_modules/.bin"
+    if not _local_bin(spec.rsplit("/", 1)[-1], cwd):
+        return f"{tool} {spec[:40]}: not installed in node_modules/.bin, so it would fetch the package"
+    return None
+
+
+def _install(toks, cwd):
+    tool = os.path.basename(toks[0]).lower()
+    args = toks[1:]
+    plain = [a for a in args if not a.startswith("-")]
+    sub = plain[0] if plain else ""
+    if tool in ("pnpx", "bunx", "uvx") or (tool in ("pnpm", "yarn") and sub == "dlx") or (tool == "bun" and sub == "x"):
+        return f"{tool} {sub if tool in ('pnpm', 'yarn', 'bun') else ''}".rstrip() + " fetches and runs a package"
+    if tool == "yarn" and sub == "global":
+        return "yarn global changes this machine"
+    if tool == "uv" and sub == "tool" and len(plain) > 1 and plain[1] in ("run", "install", "upgrade"):
+        return f"uv tool {plain[1]} fetches a package"
+    if tool == "pipx" and sub in ("run", "install", "inject", "upgrade", "reinstall", "install-all"):
+        return f"pipx {sub} fetches a package"
+    if tool == "npx" or (tool == "npm" and sub in ("exec", "x")):
+        return _npx(tool, args if tool == "npx" else args[args.index(sub) + 1:], cwd)
+    if tool in ("npm", "pnpm", "yarn", "bun"):
+        adds = {"npm": ("install", "i", "in", "add", "isntall", "install-test", "it", "install-ci-test", "cit"),
+                "pnpm": ("install", "i", "add"), "yarn": ("add",), "bun": ("install", "i", "add")}[tool]
+        if sub in adds and (len(plain) > 1 or sub == "add"):
+            return f"{tool} {sub} {plain[1] if len(plain) > 1 else ''}".rstrip() + " adds a package"
+        if sub in ("update", "upgrade", "up", "dedupe", "upgrade-interactive"):
+            return f"{tool} {sub} rewrites the lockfile"
+        if "-g" in args or "--global" in args:
+            return f"{tool} global install changes this machine"
+        restores = sub in ("install", "i", "ci", "install-test", "it", "install-ci-test", "cit") or (tool == "yarn" and sub == "")
+        if restores and _manifest_changed(NODE_LOCKS, cwd):
+            return f"{tool} install after the run changed package.json or a lockfile"
+        return None
+    if tool in ("pip", "pip3") or (tool.startswith("python") and "-m" in args and "pip" in args):
+        rest = args[args.index("pip") + 1:] if "pip" in args and tool.startswith("python") else args
+        if rest and rest[0] == "install":
+            reqs, pkgs, skip = [], [], False
+            for i, a in enumerate(rest[1:]):
+                if skip:
+                    skip = False
+                    continue
+                if a in ("-r", "--requirement", "-c", "--constraint"):
+                    if i + 2 <= len(rest[1:]):
+                        reqs.append(rest[1:][i + 1])
+                    skip = True
+                    continue
+                if a in ("-e", "--editable"):
+                    skip = True
+                    continue
+                if not a.startswith("-") and a not in (".",):
+                    pkgs.append(a)
+            if pkgs:
+                return f"pip install {pkgs[0]} adds a package"
+            if reqs and _manifest_changed([os.path.basename(r) for r in reqs] + ["pyproject.toml"], cwd):
+                return "pip install -r after the run changed the requirements file"
+        return None
+    if tool in ("uv", "poetry", "pdm", "pipenv"):
+        if sub == "add" or (tool == "uv" and sub == "pip" and len(plain) > 1 and plain[1] == "install") or (tool == "pipenv" and sub == "install" and len(plain) > 1):
+            return f"{tool} {sub} adds a package"
+        return None
+    if tool == "pod":
+        if sub == "update":
+            return "pod update rewrites Podfile.lock"
+        if sub == "install" and _manifest_changed(["Podfile", "Podfile.lock"], cwd):
+            return "pod install after the run changed the Podfile"
+        return None
+    if tool == "gem" and sub == "install":
+        return "gem install adds a package"
+    if tool == "bundle" and sub in ("add", "update"):
+        return f"bundle {sub} changes the Gemfile"
+    if tool == "brew" and sub in ("install", "reinstall", "tap", "upgrade"):
+        return f"brew {sub} changes this machine"
+    if tool == "cargo" and sub in ("add", "install", "update"):
+        return f"cargo {sub} adds or updates a package"
+    if tool == "go" and sub == "get":
+        return "go get adds a module"
+    if tool == "go" and sub == "install" and any("@" in a for a in plain[1:]):
+        return "go install <pkg>@<version> fetches a module"
+    if tool == "swift" and sub == "package" and len(plain) > 1 and plain[1] in ("add-dependency", "update"):
+        return f"swift package {plain[1]} changes Package.resolved"
+    return None
+
+
+SECURITY_READS = re.compile(r"^(find-[a-z-]+|dump-keychain|export|dump-trust-settings|add-[a-z-]+password|set-[a-z-]+|delete-[a-z-]+password|import)$")
+
+
+WEB_SCHEMES = ("http", "https", "ws", "wss", "ftp")
+
+
+def _web_url_refusal(url, policy, env, tool):
+    """Host-check a URL that a browser would load; an app's own deep-link
+    scheme opens the app under test and passes."""
+    m = re.match(r"^([A-Za-z][A-Za-z0-9+.-]*):", url)
+    scheme = m.group(1).lower() if m else ""
+    if scheme and scheme not in WEB_SCHEMES and "://" in url:
+        return None
+    return check_url_host(url, policy, env, tool)
+
+
+LAUNCHCTL_READS = {"list", "print", "print-cache", "print-disabled", "blame", "help", "version", "error", "examine"}
+DEFAULTS_READS = {"read", "read-type", "domains", "find", "help"}
+
+
+def host_command_refusal(base, toks, policy, env):
+    """Commands that change this machine or send outward without a write
+    target the guard models: persistent jobs, preferences, distribution
+    uploads, and URLs opened in a browser."""
+    plains = [a for a in toks[1:] if not a.startswith("-")]
+    if base == "crontab" and toks[1:] != ["-l"]:
+        return "crontab installs a job that runs as the operator"
+    if base == "launchctl" and not (plains and plains[0] in LAUNCHCTL_READS):
+        return "launchctl changes which jobs this machine runs"
+    if base == "defaults" and not (plains and plains[0] in DEFAULTS_READS):
+        return "defaults writes this machine's preferences"
+    if base in ("altool", "notarytool"):
+        return f"{base} uploads to Apple or stores a credential"
+    if base == "simctl" and plains and plains[0] == "openurl":
+        return _web_url_refusal(plains[-1], policy, env, "simctl openurl") if len(plains) >= 3 else None
+    if base == "open":
+        for a in plains:
+            if "://" not in a or not re.match(r"^(https?)://", a, re.I):
+                return "open launches an application or a file the guard cannot judge"
+            r = check_url_host(a, policy, env, "open")
+            if r:
+                return r
+        return None if plains else "open with no URL cannot be judged"
+    return None
+
+
+def _publisher(toks, policy):
+    scripts = policy.get("publisherScripts", {})
+    for i, t in enumerate(toks[:3]):
+        base = os.path.basename(t)
+        if base in scripts and not base.startswith("$"):
+            subs = scripts[base]
+            rest = [a for a in toks[i + 1:] if not a.startswith("-")]
+            if subs is None or (rest and rest[0] in subs):
+                return f"{base} publishes outward, reads a credential or changes device access; an unattended run may not"
+            if rest and (_has_ph(rest[0]) or rest[0].startswith("$")):
+                return f"{base} with a subcommand built at run time cannot be judged"
+    return None
+
+
+# --- variables, cwd and write targets -----------------------------------------
+
+VAR_RX = re.compile(r"\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))")
+
+
+def expand(text, variables, env=None):
+    """text with $NAME / ${NAME} expanded from the variables this command set,
+    then HOME, then the hook's environment. None when any part cannot be
+    resolved: a substitution placeholder, an unknown variable, or a `$` form
+    other than a plain name."""
+    if _has_ph(text):
+        return None
+    env = os.environ if env is None else env
+    unresolved = False
+
+    def sub(m):
+        nonlocal unresolved
+        name = m.group(1) or m.group(2)
+        if name in variables:
+            v = variables[name]
+        elif name == "HOME":
+            v = home()
+        else:
+            v = env.get(name)
+        if v is None:
+            unresolved = True
+            return ""
+        return v
+
+    out = VAR_RX.sub(sub, text)
+    if unresolved or "$" in out:
+        return None
+    return out
+
+
+class Ctx:
+    """Per-command state: the cwd after any cd (None once it cannot be
+    resolved), and the variables set by earlier simple assignments."""
+
+    def __init__(self, cwd, policy, env, variables=None, inners=None):
+        self.cwd = cwd
+        self.policy = policy
+        self.env = env
+        self.vars = dict(variables or {})
+        self.inners = inners or []
+        # Set per segment: whether the segment has a glob character outside
+        # quotes, so a globbed write target can be told from a quoted one.
+        self.unquoted_glob = False
+
+    def target(self, raw):
+        """Reason a write target is refused, or None."""
+        path = raw.strip("'\"")
+        if path in ("/dev/null", "/dev/stderr", "/dev/stdout") or path.startswith("&"):
+            return None
+        if self.unquoted_glob and any(ch in path for ch in GLOB_CHARS):
+            return f"write target '{path[:60]}' is a glob pattern the shell expands to paths the guard cannot see"
+        e = expand(path, self.vars, self.env)
+        if e is None:
+            return f"write target '{path[:60]}' is built at run time and cannot be checked"
+        e = os.path.expanduser(e)
+        if self.cwd is None and not os.path.isabs(e):
+            return f"write target '{path[:60]}' is relative to a directory the guard could not resolve"
+        return check_path(e, self.cwd, self.policy, self.env)
+
+
+def check_segment(seg, ctx):
+    policy, env = ctx.policy, ctx.env
+    r = dangerous_assignment(tokenize(seg))
+    if r:
+        return r
+    toks = _strip_wrappers(tokenize(seg))
+    if not toks:
+        return None
+    if "$" in toks[0]:
+        e = expand(toks[0], ctx.vars, env)
+        if e is None:
+            return "the command name is built at run time and cannot be judged"
+        toks = [e] + toks[1:]
+    base = os.path.basename(toks[0]).lower()
+
+    def targets(ts):
+        for t in ts:
+            r = ctx.target(t)
+            if r:
+                return r
+        return None
+
+    if base == "git":
+        r = git_config_refusal(toks) or git_global_flag_refusal(toks)
+        if r:
+            return r
+        sub, rest = _git_sub(toks)
+        if _has_ph(sub) or sub.startswith("$"):
+            return "a git subcommand built at run time cannot be judged"
+        r = git_exec_refusal(sub, rest, toks)
+        if r:
+            return r
+        r = git_url_refusal(sub, rest, toks, policy, env)
+        if r:
+            return r
+        # git apply / am write files a diff names, which the guard cannot
+        # enumerate. The run's own work is committed, not applied from a patch;
+        # refused unattended, and the sandbox confines the paths if it ran.
+        if sub in ("apply", "am") and not any(
+            a.startswith("--directory") for a in rest
+        ):
+            return f"git {sub} applies a diff that names files the guard cannot enumerate; refused unattended"
+        if sub == "push":
+            return "git push: the runner pushes after it verifies pr-request.json"
+        if sub == "send-email":
+            return "git send-email sends mail"
+        if sub == "remote" and rest and rest[0] in ("add", "set-url", "rename", "remove", "rm", "set-head"):
+            return f"git remote {rest[0]} changes where the runner would push"
+        if sub == "config":
+            r = _git_config(rest)
+            if r:
+                return r
+        return targets(extractor_write_targets(toks))
+    if base == "gh":
+        plains = [a for a in toks[1:] if not a.startswith("-")]
+        if any(_has_ph(a) or a.startswith("$") for a in plains[:2]):
+            return "a gh command group or verb built at run time cannot be judged"
+        return _gh(toks, policy, env)
+    if base == "security" and len(toks) > 1:
+        j = 1
+        while j < len(toks) and toks[j].startswith("-"):
+            j += 2 if toks[j] == "-p" else 1
+        sub = toks[j] if j < len(toks) else ""
+        if SECURITY_READS.match(sub):
+            return f"security {sub} reads or writes the Keychain"
+        if _has_ph(sub) or sub.startswith("$"):
+            return "a security subcommand built at run time cannot be judged"
+    r = network_tool_refusal(base)
+    if r:
+        return r
+    if base == "rsync":
+        # rsync src host:path (or host::module) transfers to a remote the
+        # allowlist cannot check; a local `-e` remote shell is the same.
+        for a in toks[1:]:
+            if a.startswith("-"):
+                continue
+            if re.match(r"^[A-Za-z0-9_.-]+@?[A-Za-z0-9_.-]*:", a) and not os.path.isabs(a) and "://" not in a:
+                return "rsync to a remote host cannot be checked against the allowlist; refused unattended"
+        if any(a in ("-e", "--rsh") or a.startswith("--rsh=") or a.startswith("-e") and len(a) > 2 for a in toks[1:]):
+            return "rsync -e runs a remote shell the guard cannot see"
+    r = host_command_refusal(base, toks, policy, env)
+    if r:
+        return r
+    if base in ("curl", "wget"):
+        r = _fetch(toks, policy, env)
+        if r:
+            return r
+        return targets(extractor_write_targets(toks))
+    if base == "patch":
+        return "patch applies a diff that names files the guard cannot enumerate; refused unattended"
+    if base in ("tar", "gtar", "bsdtar"):
+        # An archive extraction whose members carry absolute paths (-P) writes
+        # anywhere; without -P the paths are under the extraction directory,
+        # which -C names and check_path judges (the sandbox confines the rest).
+        if any(_short_cluster_has(a, "P") or a == "--absolute-names" for a in toks[1:]):
+            return "tar -P / --absolute-names extracts to absolute paths the guard cannot enumerate"
+        r = targets(extractor_write_targets(toks))
+        if r:
+            return r
+    if base in ("unzip", "cpio", "pax", "7z", "7za", "diff", "gdiff", "xcodebuild"):
+        r = targets(extractor_write_targets(toks))
+        if r:
+            return r
+    if base == "swift":
+        r = targets(extractor_write_targets(toks))
+        if r:
+            return r
+    plains = [a for a in toks[1:] if not a.startswith("-")]
+    if base in ("npm", "pnpm", "yarn", "bun", "npx", "pip", "pip3", "uv", "poetry", "pdm", "pipenv", "pod", "gem",
+                "bundle", "brew", "cargo", "go", "swift") and plains and _has_ph(plains[0]):
+        return f"{base} with a subcommand built at run time cannot be judged"
+    r = _install(toks, ctx.cwd or os.getcwd())
+    if r:
+        return r
+    r = _publisher(toks, policy)
+    if r:
+        return r
+    return targets(write_targets(toks))
+
+
+REDIRECT = re.compile(r"(?:^|[^0-9&<>])(?:\d?>>?|&>>?|>\|)\s*([^\s;&|<>]+)")
+ASSIGN_RX = re.compile(r"^([A-Za-z_][A-Za-z0-9_]*)=(.*)$", re.S)
+
+
+def _cd(stripped, ctx):
+    """New cwd after cd/pushd/popd: a resolved absolute path, or None."""
+    cmd = os.path.basename(stripped[0]).lower()
+    if cmd == "popd":
+        return None
+    # `cd -` returns to $OLDPWD, which the guard does not track: the new cwd is
+    # unknown, so anything after it is judged with no directory (and refused if
+    # it needs one). Caught before the flag filter drops the "-".
+    if any(t == "-" for t in stripped[1:]):
+        return None
+    args = [t for t in stripped[1:] if not t.startswith("-")]
+    if not args:
+        return home() if cmd == "cd" else None
+    e = expand(args[0], ctx.vars, ctx.env)
+    if e is None or any(ch in e for ch in GLOB_CHARS):
+        return None
+    e = os.path.expanduser(e)
+    if not os.path.isabs(e):
+        # With CDPATH set, `cd name` may land in a CDPATH entry instead.
+        cdpath = (os.environ if ctx.env is None else ctx.env).get("CDPATH")
+        if cdpath and not (e == "." or e == ".." or e.startswith("./") or e.startswith("../")):
+            return None
+        if ctx.cwd is None:
+            return None
+        e = os.path.join(ctx.cwd, e)
+    return os.path.normpath(e)
+
+
+def check_bash(cmd, cwd, policy, env=None, variables=None, nested=False):
+    try:
+        if not nested:
+            cmd = strip_heredocs(cmd)
+        outer, inners = extract_substitutions(cmd)
+    except Refused as e:
+        return str(e)
+    if nested and inners:
+        return "a command substitution nested inside another is not analysed"
+    r = structural_refusal(outer)
+    if r:
+        return r
+    ctx = Ctx(cwd or os.getcwd(), policy, env, variables, inners)
+    for seg in split_ops(outer):
+        # Every substitution in this segment runs first, in the segment's cwd,
+        # and must pass the same checks as if it were typed directly.
+        for m in PLACEHOLDER_RX.finditer(seg):
+            inner = inners[int(m.group(1))]
+            if not inner.strip():
+                return "an empty command substitution"
+            if ctx.cwd is None:
+                return "a command substitution after a cd the guard could not resolve"
+            r = check_bash(inner, ctx.cwd, policy, env, ctx.vars, nested=True)
+            if r:
+                return f"inside $(...): {r}"
+        toks = tokenize(seg)
+        ctx.unquoted_glob = any(ch in _strip_quotes(seg, keep_double=False) for ch in GLOB_CHARS)
+        r = simple_command_refusal(seg, toks, ctx.vars, env, ctx.cwd)
+        if r:
+            return r
+        stripped = _strip_wrappers(toks)
+        if stripped and os.path.basename(stripped[0]).lower() in ("cd", "pushd") and ctx.unquoted_glob:
+            if any(ch in a for a in stripped[1:] for ch in GLOB_CHARS):
+                return "cd into a glob pattern moves the run to a directory the guard cannot see"
+        try:
+            redirects = redirect_targets(seg)
+        except Refused as e:
+            return str(e)
+        for t in redirects:
+            r = ctx.target(t)
+            if r:
+                return r
+        r = check_segment(seg, ctx)
+        if r:
+            return r
+        stripped = _strip_wrappers(toks)
+        if stripped and os.path.basename(stripped[0]).lower() in ("cd", "pushd", "popd"):
+            ctx.cwd = _cd(stripped, ctx)
+        elif toks and all(ASSIGN_RX.match(t) for t in toks):
+            # A bare assignment line: remember what it set for later expansion.
+            for t in toks:
+                name, value = ASSIGN_RX.match(t).groups()
+                ctx.vars[name] = expand(value, ctx.vars, env)
+    return None
+
+
+TOOLKIT_PREFIX = "mcp__multi-agent-toolkit__"
+
+
+# Keys a toolkit tool uses for a filesystem destination it writes. Checked with
+# check_path so a toolkit call cannot write a screenshot, recording, build
+# output or export over a protected path. MCP tools run outside the OS sandbox,
+# so this is their only path boundary.
+TOOLKIT_PATH_KEYS = ("path", "filename", "out_dir", "output_path", "output_dir",
+                     "export_path", "derived_data_path", "result_bundle_path",
+                     "figma_path", "screenshot_path", "video_path", "file_path")
+
+
+def _toolkit_path_refusal(name, ti, policy, env, cwd):
+    for key, value in ti.items():
+        if not isinstance(value, str) or not value:
+            continue
+        if key in TOOLKIT_PATH_KEYS or key.endswith("_path"):
+            r = check_path(value, cwd, policy, env)
+            if r:
+                return f"{name} {key}: {r}"
+    return None
+
+
+def check_toolkit(name, ti, policy, env, depth=0, cwd=None):
+    """A multi-agent-toolkit tool call, by its short name (web_goto,
+    ios_open_url, agent_run_steps). agent_run_steps dispatches other toolkit
+    tools, so each step is judged as if it were called directly. Every
+    path-typed argument is checked, including inside a step."""
+    if not isinstance(ti, dict):
+        return f"{name} arguments are not an object the guard can read"
+    if name.startswith("research_"):
+        return f"{name} sends the query to an outside service"
+    if name == "web_eval":
+        return "web_eval runs arbitrary JavaScript that can reach any host; refused unattended"
+    if name == "agent_run_steps":
+        steps = ti.get("steps")
+        if depth or not isinstance(steps, list):
+            return "agent_run_steps without a readable list of steps cannot be judged"
+        for step in steps:
+            if not isinstance(step, dict) or not isinstance(step.get("tool"), str):
+                return "an agent_run_steps step without a tool name cannot be judged"
+            sub = step["tool"]
+            sub = sub[len(TOOLKIT_PREFIX):] if sub.startswith(TOOLKIT_PREFIX) else sub
+            if sub.startswith("agent_"):
+                return "agent_run_steps may not nest another agent_* tool"
+            r = check_toolkit(sub, step.get("args") if step.get("args") is not None else {}, policy, env, depth + 1, cwd)
+            if r:
+                return f"agent_run_steps step {sub}: {r}"
+        return None
+    r = _toolkit_path_refusal(name, ti, policy, env, cwd)
+    if r:
+        return r
+    if "url" in ti and not isinstance(ti["url"], str):
+        # A non-string url (a list, an object) is not something the guard can
+        # host-check; a web tool handed one is refused rather than waved through.
+        return f"{name} was given a url that is not a string; the host cannot be checked"
+    url = ti.get("url")
+    if not isinstance(url, str) or not url:
+        return None
+    if name.startswith("web_"):
+        return check_url_host(url, policy, env, name)
+    return _web_url_refusal(url, policy, env, name)
+
+
+def check(payload, env=None):
+    """Reason string when the tool call is blocked, None when it is allowed."""
+    policy = load_policy()
+    tool = payload.get("tool_name") or ""
+    ti = payload.get("tool_input") or {}
+    cwd = payload.get("cwd") or os.getcwd()
+    if tool in ("Edit", "Write", "NotebookEdit", "MultiEdit"):
+        return check_path(ti.get("file_path") or ti.get("notebook_path") or "", cwd, policy, env)
+    if tool.startswith(TOOLKIT_PREFIX):
+        return check_toolkit(tool[len(TOOLKIT_PREFIX):], ti, policy, env, cwd=cwd)
+    if tool == "WebFetch":
+        url = ti.get("url")
+        if isinstance(url, str) and url:
+            return check_url_host(url, policy, env, "WebFetch")
+        return None
+    cmd = ti.get("command")
+    if isinstance(cmd, str) and cmd:
+        return check_bash(cmd, cwd, policy, env)
+    return None
+
+
+# --- git subcommand tokenizer, reused by pre-commit-check.sh ------------------
+
+GIT_COMMIT_LIKE = {"commit", "commit-tree", "merge", "cherry-pick", "revert", "am"}
+
+
+def git_subcommands(cmd, depth=0):
+    """Every git subcommand across the simple commands of a shell line,
+    including those inside `$(...)`, using the same wrapper-stripping and
+    casefolding the guard uses. Refuse-structure is NOT applied here: the
+    caller (pre-commit) only needs to know whether a commit happens."""
+    subs = []
+    inners = []
+    if depth == 0:
+        try:
+            cmd = strip_heredocs(cmd)
+        except Refused:
+            pass
+    if depth < 3:
+        try:
+            cmd, inners = extract_substitutions(cmd)
+        except Refused:
+            inners = []
+    for seg in split_ops(cmd):
+        toks = _strip_wrappers(tokenize(seg))
+        if not toks:
+            continue
+        if os.path.basename(toks[0]).lower() == "git":
+            sub, rest = _git_sub(toks)
+            if sub:
+                subs.append(sub)
+            # A git alias could expand to a commit; treat an alias as commit-like.
+            if git_config_refusal(toks):
+                subs.append("commit")
+    for inner in inners:
+        subs.extend(git_subcommands(inner, depth + 1))
+    return subs
+
+
+COMMIT_WRITERS = ("commit", "commit-tree", "merge", "cherry-pick", "revert", "am")
+
+
+def _git_dir_opt(toks):
+    """The directory named by git's global `-C`, or None."""
+    i = 1
+    while i < len(toks):
+        t = toks[i]
+        if t == "-C" and i + 1 < len(toks):
+            return toks[i + 1]
+        if t in ("-c", "--git-dir", "--work-tree", "--exec-path", "--namespace"):
+            i += 2
+        elif t.startswith("-"):
+            i += 1
+        else:
+            return None
+    return None
+
+
+def _literal_dir(arg, cwd):
+    """`arg` as an absolute directory, expanding a leading `~` / `$HOME` /
+    `${HOME}` from the environment; "" when anything else would need the shell
+    (a variable, a substitution, a glob, `~user`, `-`) or the base is unknown."""
+    home = os.environ.get("HOME", "")
+    for prefix in ("${HOME}", "$HOME", "~"):
+        if home and (arg == prefix or arg.startswith(prefix + "/")):
+            arg = home + arg[len(prefix):]
+            break
+    if not arg or arg == "-" or any(ch in arg for ch in "$`~*?"):
+        return ""
+    if os.path.isabs(arg):
+        return os.path.normpath(arg)
+    if cwd == "":
+        return ""
+    return os.path.normpath(os.path.join(cwd, arg))
+
+
+def git_commit_dirs(cmd, base):
+    """The directory each commit-writing git command on a shell line runs in,
+    following `cd`/`pushd` and git's `-C` from `base`. "" marks a directory the
+    line names in a way that cannot be read literally (`cd "$X"`, `cd -`)."""
+    try:
+        cmd = strip_heredocs(cmd)
+    except Refused:
+        pass
+    cwd = base
+    dirs = []
+    for seg in split_ops(cmd):
+        toks = _strip_wrappers(tokenize(seg))
+        if not toks:
+            continue
+        head = os.path.basename(toks[0]).lower()
+        if head in ("cd", "pushd"):
+            args = [t for t in toks[1:] if t == "-" or not t.startswith("-")]
+            cwd = _literal_dir(args[0], cwd) if args else ""
+            continue
+        if head != "git":
+            continue
+        sub, _ = _git_sub(toks)
+        if sub not in COMMIT_WRITERS:
+            continue
+        opt = _git_dir_opt(toks)
+        dirs.append(cwd if opt is None else _literal_dir(opt, cwd))
+    return dirs