@miller-tech/uap 2.1.6 → 2.11.0

package/tools/agents/scripts/tool_risk.py

@@ -0,0 +1,789 @@
+"""AutoMode pre-execution risk classification — advisory heuristic scorer.
+
+Uplift 1.3. Classifies each tool call BEFORE dispatch into one of five risk
+classes (destructive / write / execute / read / network) with a 1-5 score.
+The output is ADVISORY to the deterministic policy chain: the enforcers in
+src/policies/enforcers/*.py remain the blocking floor; this scorer never
+blocks and never loosens anything. It exists so the proxy/enforcer stack has
+an AutoMode risk signal NOW. Its vocabulary is INSPIRED BY the unmerged
+TypeScript SYS1 baseline (src/classify/baseline.ts on
+feature/301-sys1-classifier, the ESCALATION_TOKENS / DESTRUCTIVE_TOKENS
+lists) — deliberately not "ported": that baseline scores prose state
+descriptions while this scorer parses shell structure, so the domains and
+machinery differ. The SYS1 promotion path is a Python-resident head (or
+sidecar) behind this same classify_tool_call contract, gated by the
+calibration harness at held-out destructive recall 1.0 — the wiring, harness
+and doctrine do not change when it lands.
+
+Design rules:
+  * PURE: no I/O, no clock except the latency measurement at the boundary.
+  * AUDITABLE: every point of score is attributable to a named signal in
+    ``signals`` (format "name:class+weight").
+  * FAIL-CLOSED ON DESTRUCTIVE: a missed destructive call is the unacceptable
+    error (held-out destructive recall is gated at 1.0 by
+    tool_risk_calibrate.py --check); false positives are advisory-only cost.
+  * ALIGNED, NOT DUPLICATED: launcher prefixes, conditional-verb semantics
+    (sed -i, find -delete) and protected-surface markers mirror
+    src/policies/enforcers/enforcement_self_protect.py so both layers see the
+    same evasion shapes (nohup/timeout/sudo/env prefixes, &&/;/| chaining,
+    trailing-slash and ./ path variants, .uap/.git self-targets).
+
+Calibration: docs/performance/automode-risk-calibration.md, generated by
+tool_risk_calibrate.py from tools/agents/tests/fixtures/tool_risk_cases.json.
+"""
+from __future__ import annotations
+
+import posixpath
+import re
+import shlex
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Literal
+
+RiskClass = Literal["destructive", "write", "execute", "read", "network"]
+RISK_CLASSES: tuple[RiskClass, ...] = (
+    "destructive", "write", "execute", "read", "network",
+)
+
+# Tie-break order when two classes tie on total signal weight: the more
+# severe class wins (advisory pessimism is cheap; a missed destructive call
+# is not).
+_SEVERITY: tuple[RiskClass, ...] = (
+    "destructive", "network", "write", "execute", "read",
+)
+
+_BASE_SCORE: dict[RiskClass, int] = {
+    "read": 1, "execute": 2, "write": 3, "network": 3, "destructive": 4,
+}
+# A class whose signals reach this total weight is a "hard" instance of the
+# class and scores base+1 (capped at 5).
+_HARD_SIGNAL_WEIGHT = 5
+
+
+@dataclass(frozen=True)
+class RiskAssessment:
+    """Outcome of one advisory classification.
+
+    risk_class: one of RISK_CLASSES. risk_score: 1 (benign) .. 5 (hard
+    destructive). signals: every signal that fired, "name:class+weight" —
+    the score is exactly derivable from this list. latency_ms: wall time of
+    the pure computation (populated by classify_tool_call).
+    """
+
+    risk_class: RiskClass
+    risk_score: int
+    signals: list[str]
+    latency_ms: float
+
+
+# A signal is (name, class, weight); formatted into RiskAssessment.signals.
+_Signal = tuple[str, RiskClass, int]
+_SignalFn = Callable[[str, list[str], str, int, "list[_Signal]"], None]
+
+
+# --- shell lexing (aligned with enforcers/enforcement_self_protect.py) -----
+
+# Split chained commands. Single & is a separator (backgrounding) — the
+# enforcer uses the same class and accepts that `2>&1` splits here too.
+_SEGMENT_SPLIT = re.compile(r"(?:\|\||&&|[;\n|&])")
+_ENV_ASSIGN = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*=\S*$")
+# Output redirection. The negative lookahead keeps fd duplication (`2>&1`)
+# from counting as a file write; the target group accepts a quoted token so
+# `> "out file.txt"` is still one target.
+_REDIRECT = re.compile(
+    r">>?(?!\s*&)\s*(\"[^\"\n]*\"|'[^'\n]*'|[^\s;|&]*)"
+)
+_QUOTED = re.compile(r'"[^"\n]*"|\'[^\'\n]*\'')
+
+
+def _blank_quotes(text: str) -> str:
+    """Blank quoted INTERIORS to spaces, preserving the quote characters and
+    the total length. Two properties ride on this:
+
+    * offsets are preserved, so a separator or operator position in the
+      blanked copy is the same position in the original (segment splitting
+      and redirect scanning can slice the original by the blanked span);
+    * a quoted TOKEN survives as a quoted token, so a quoted redirect target
+      (`> ".uap/x"`, `> "out file.txt"`) keeps its quotes and its span —
+      while quoted PROSE (`echo "rm -rf /"`) blanks to inert spaces and can
+      never reach verb position.
+
+    Known residual (documented in docs/reference/automode-risk.md): an
+    ESCAPED quote inside a double-quoted string (`"a=\\";\\"; rm -rf /x"`)
+    ends the match early, because the regex does not model backslash escapes
+    — same accepted-residual class as paths held in shell variables."""
+    def _sub(m: "re.Match") -> str:
+        s = m.group(0)
+        return s[0] + " " * (len(s) - 2) + s[-1]
+
+    return _QUOTED.sub(_sub, text)
+# Launcher prefixes that run the REAL command as their tail — stepping over
+# them (and their flags/values) is what makes `sudo rm -rf /`,
+# `nohup rm -rf x &` and `timeout 10 rm -rf y` visible. Same list the
+# self-protect enforcer steps over.
+_LAUNCHERS = frozenset({
+    "nohup", "timeout", "command", "builtin", "setsid", "sudo", "doas",
+    "nice", "ionice", "stdbuf", "time", "unbuffer", "env",
+})
+_SHELL_VERBS = frozenset({"sh", "bash", "zsh", "dash", "ash", "ksh", "mksh"})
+_INTERPRETERS = frozenset({
+    "python", "python2", "python3", "perl", "ruby", "node", "nodejs", "php", "lua",
+})
+_SQL_CLIENTS = frozenset({
+    "psql", "mysql", "mariadb", "sqlite3", "sqlplus",
+    "redis-cli", "mongo", "mongosh", "clickhouse-client",
+})
+_PKG_MANAGERS = frozenset({
+    "npm", "yarn", "pnpm", "pip", "pip3", "pipx",
+    "apt", "apt-get", "dpkg", "dnf", "yum", "brew",
+})
+_PLATFORM_CLIS = frozenset({
+    "docker", "podman", "kubectl", "terraform", "tofu", "aws", "gcloud",
+    "az", "systemctl", "go", "cargo",
+})
+# Regenerable trees whose removal is routine maintenance, not destruction:
+# `rm -rf ./node_modules/.cache` must NOT classify destructive. Membership is
+# by path COMPONENT so `./build`, `pkg/dist` and `/tmp/x` all resolve.
+_SCRATCH_COMPONENTS = frozenset({
+    "node_modules", ".cache", "__pycache__", ".pytest_cache", ".mypy_cache",
+    ".ruff-cache", ".ruff_cache", ".next", ".turbo", ".parcel-cache",
+    "dist", "build", "coverage", "out", "target", ".venv",
+})
+# The enforcement control surface. A destructive op naming any of these gets
+# a score bump — this is the advisory mirror of the self-protect enforcer's
+# PROTECTED_MARKERS (deliberately a coarse substring/regex net: advisory
+# over-trigger is free).
+_PROTECTED_RE = re.compile(
+    r"\.uap(?:[\s/'\".]|$)|(?:^|[\s/'\"])\.git(?:[\s/'\"]|$)"
+    r"|src/policies|\.policy-tools|policies\.db|anthropic-proxy\.env"
+)
+
+_READ_VERBS = frozenset({
+    "ls", "cat", "head", "tail", "wc", "grep", "egrep", "fgrep", "rg", "ag",
+    "ack", "ps", "df", "du", "pwd", "which", "file", "stat", "jq", "tree",
+    "less", "more", "id", "uname", "hostname", "date", "echo", "printf",
+    "cd", "printenv", "whoami", "lsblk", "lsof", "true", "false", "test",
+})
+_WRITE_VERBS = frozenset({
+    "cp", "mv", "mkdir", "touch", "ln", "tee", "install", "patch",
+    "unzip", "unrar", "gunzip", "bunzip2", "chattr", "zip", "gzip", "bzip2",
+})
+_EXEC_VERBS = frozenset({
+    "make", "ninja", "cmake", "pytest", "jest", "vitest", "mocha", "tox",
+    "nox", "gradle", "mvn", "kill", "pkill", "killall", "xargs", "source",
+})
+# find only mutates under a flag; sed only under -i. Mirrors the enforcer's
+# CONDITIONAL_VERBS semantics.
+_FIND_MUTATING = frozenset({
+    "-delete", "-exec", "-execdir", "-ok", "-okdir",
+    "-fprint", "-fprint0", "-fprintf", "-fls",
+})
+_INTERP_DESTRUCTIVE_RE = re.compile(
+    r"shutil\.rmtree|rmtree|os\.remove|os\.unlink|\.unlink\(|"
+    r"os\.removedirs|os\.rmdir|pathlib.*\.rmtree"
+)
+_INTERP_WRITE_RE = re.compile(
+    r"open\s*\([^)]*['\"][wax+]|\.write\(|\.writelines\(|json\.dump\("
+)
+_SQL_DROP_RE = re.compile(
+    r"\bdrop\s+(table|database|schema|index|collection)\b|dropdatabase\s*\(|"
+    r"\bflush(all|db)\b",
+    re.I,
+)
+_SQL_TRUNCATE_RE = re.compile(r"\btruncate\b", re.I)
+_SQL_DELETE_RE = re.compile(r"\bdelete\s+from\b", re.I)
+_SQL_WRITE_RE = re.compile(r"\b(insert\s+into|update\s+\w+\s+set|alter\s+table|create\s+table)\b", re.I)
+
+
+def _verb_of(token: str) -> str:
+    """The command a token invokes, quoting/\\-escaping/path-prefix removed.
+
+    Same normalisation as the self-protect enforcer's `_verb_of`.
+    """
+    return token.strip("\"'").lstrip("\\").rsplit("/", 1)[-1].lower()
+
+
+def _split_tokens(segment: str) -> list[str]:
+    """shlex split with a naive fallback for unbalanced quotes."""
+    try:
+        return shlex.split(segment, posix=True)
+    except ValueError:
+        return segment.split()
+
+
+def _is_scratch_target(token: str) -> bool:
+    """True when an rm target is a regenerable scratch path (or under /tmp)."""
+    t = token.strip("\"'").rstrip("/")
+    norm = posixpath.normpath(t) if "/" in t else t
+    if norm.startswith("/tmp/"):
+        return True
+    return any(part in _SCRATCH_COMPONENTS for part in norm.split("/"))
+
+
+def _first_operand(rest: list[str]) -> tuple[str, list[str]]:
+    """First non-flag token and what follows it (subcommand extraction)."""
+    for i, tok in enumerate(rest):
+        if not tok.startswith("-"):
+            return tok.lower(), rest[i + 1:]
+    return "", []
+
+
+# --- per-verb signal functions (each small; one audit unit per rule) -------
+# Uniform signature: fn(verb, rest, segment, depth, signals) -> None
+
+def _sig_redirects(segment: str, signals: list[_Signal]) -> None:
+    """Output redirects are writes; a device target is destructive.
+
+    Operators are found on the quote-BLANKED text (so `echo "a > b"` is not
+    a write), but the target is sliced from the ORIGINAL segment at the same
+    span — blanking preserves length, so a quoted target (`> ".uap/x"`,
+    `> "out file.txt"`) arrives with its real name for the protected check.
+    """
+    blanked = _blank_quotes(segment)
+    for m in _REDIRECT.finditer(blanked):
+        target = segment[m.start(1):m.end(1)].strip("\"'")
+        if not target:
+            tail = segment[m.end():].split()
+            target = tail[0].strip("\"'") if tail else ""
+        if not target or target == "/dev/null":
+            continue
+        if target.startswith("/dev/"):
+            signals.append(("device-write", "destructive", 5))
+        elif _PROTECTED_RE.search(target.lower()):
+            signals.append(("protected-redirect", "write", 3))
+        else:
+            signals.append(("file-redirect", "write", 2))
+
+
+def _sig_shell_wrap(verb: str, rest: list[str], segment: str, depth: int,
+                    signals: list[_Signal]) -> None:
+    """sh/bash -c '...' and eval: unwrap and classify the inner command."""
+    signals.append(("shell-wrap", "execute", 1))
+    if depth >= 2:  # bounded: bash -c "bash -c ..." can't recurse forever
+        return
+    if verb == "eval":
+        inner = " ".join(rest).strip()
+        if inner:
+            _classify_command(inner, depth + 1, signals)
+        return
+    for i, tok in enumerate(rest):
+        if tok == "-c" and i + 1 < len(rest):
+            _classify_command(rest[i + 1], depth + 1, signals)
+            return
+    # No -c: a bare `bash script.sh` runs the script.
+    if rest and not rest[0].startswith("-"):
+        signals.append(("shell-script", "execute", 2))
+
+
+def _sig_interpreter(verb: str, rest: list[str], segment: str, depth: int,
+                     signals: list[_Signal]) -> None:
+    """python/node/perl -c code is scanned for write/destructive primitives;
+    a script path or -m module is an ordinary execution."""
+    if "-c" in rest:
+        if _INTERP_DESTRUCTIVE_RE.search(segment):
+            signals.append(("interpreter-destructive", "destructive", 5))
+        elif _INTERP_WRITE_RE.search(segment):
+            signals.append(("interpreter-write", "write", 2))
+        else:
+            signals.append(("interpreter-code", "execute", 2))
+    elif rest and (not rest[0].startswith("-") or rest[0] == "-m"):
+        signals.append(("interpreter-script", "execute", 2))
+    else:
+        signals.append(("interpreter-run", "execute", 1))
+
+
+def _git_subcommand(rest: list[str]) -> tuple[str, list[str]]:
+    """The git subcommand, stepping over global flags like -C/-c/--git-dir."""
+    i = 0
+    while i < len(rest):
+        tok = rest[i]
+        if tok in ("-C", "-c", "--git-dir", "--work-tree"):
+            i += 2
+            continue
+        if tok.startswith("-"):
+            i += 1
+            continue
+        return tok.lower(), rest[i + 1:]
+    return "", []
+
+
+def _sig_git_push(args: list[str], signals: list[_Signal]) -> None:
+    flags = [t for t in args if t.startswith("-")]
+    # --force-with-lease / --force-if-includes are the SAFE force spellings:
+    # they verify the remote ref before overwriting, so they classify as the
+    # network operation they are, not as destructive (a measured lookalike).
+    safe_force = any(
+        t == "--force-with-lease" or t.startswith("--force-with-lease=")
+        or t == "--force-if-includes"
+        for t in flags
+    )
+    hard_force = any(
+        t in ("-f", "--force")
+        or (t.startswith("-") and not t.startswith("--") and "f" in t[1:])
+        for t in flags
+    )
+    # Hard force is judged FIRST: git ignores the lease when a plain --force
+    # is present, so `--force --force-with-lease` is destructive regardless
+    # of argument order. `--no-force-with-lease` matches neither list and
+    # correctly stays an ordinary push.
+    if hard_force:
+        signals.append(("git-push-force", "destructive", 5))
+    elif safe_force:
+        signals.append(("git-push-lease", "network", 3))
+    else:
+        signals.append(("git-push", "network", 3))
+
+
+def _sig_git(verb: str, rest: list[str], segment: str, depth: int,
+             signals: list[_Signal]) -> None:
+    sub, args = _git_subcommand(rest)
+    if sub == "push":
+        _sig_git_push(args, signals)
+    elif sub == "reset":
+        if "--hard" in args:
+            signals.append(("git-reset-hard", "destructive", 5))
+        else:
+            signals.append(("git-reset-soft", "write", 2))
+    elif sub == "clean":
+        joined = "".join(t for t in args if t.startswith("-"))
+        if "f" in joined:
+            signals.append(("git-clean-force", "destructive", 4))
+        else:
+            signals.append(("git-clean-dry", "read", 1))
+    elif sub in ("checkout", "restore", "switch"):
+        # `checkout -- <path>` / `restore <path>` DISCARDS worktree edits.
+        if "--" in args or (sub == "restore" and any(not t.startswith("-") for t in args)):
+            signals.append(("git-discard-worktree", "destructive", 4))
+        else:
+            signals.append(("git-checkout", "write", 2))
+    elif sub == "branch":
+        if "-D" in args:
+            signals.append(("git-branch-force-delete", "destructive", 4))
+        elif "-d" in args:
+            signals.append(("git-branch-delete", "write", 2))
+        else:
+            signals.append(("git-branch", "read", 1))
+    elif sub in ("fetch", "pull", "clone", "remote", "ls-remote"):
+        signals.append(("git-network", "network", 3))
+    elif sub in ("add", "commit", "tag", "stash", "rebase", "merge",
+                 "cherry-pick", "mv", "rm", "worktree"):
+        signals.append(("git-write", "write", 2))
+    else:
+        # status, log, diff, show, blame, describe, rev-parse, ...
+        signals.append(("git-read", "read", 1))
+
+
+def _sig_rm_family(verb: str, rest: list[str], segment: str, depth: int,
+                   signals: list[_Signal]) -> None:
+    if verb == "shred":
+        signals.append(("shred", "destructive", 5))
+        return
+    if verb == "unlink":
+        signals.append(("unlink-file", "destructive", 3))
+        return
+    if verb == "rmdir":
+        signals.append(("rmdir", "destructive", 2))
+        return
+    flags = [t for t in rest if t.startswith("-")]
+    # Only SHORT-flag clusters carry the recursive letter (-r, -rf, -Rf).
+    # Long flags match exactly: --force does NOT contain a recursive "r"
+    # (`rm --force file` is a plain file delete), --recursive does.
+    recursive = any(
+        t == "--recursive"
+        or (not t.startswith("--") and ("r" in t[1:] or "R" in t[1:]))
+        for t in flags
+    )
+    targets = [t for t in rest if not t.startswith("-")]
+    # The scratch carve-out: removing ONLY regenerable trees (node_modules,
+    # build output, /tmp scratch) is maintenance, not destruction. Mixed
+    # target lists do not qualify — one real target keeps the class.
+    if targets and all(_is_scratch_target(t) for t in targets):
+        signals.append(("rm-scratch-target", "write", 2))
+    elif recursive:
+        signals.append(("rm-recursive", "destructive", 5))
+    else:
+        signals.append(("rm-file", "destructive", 3))
+
+
+def _sig_find(verb: str, rest: list[str], segment: str, depth: int,
+              signals: list[_Signal]) -> None:
+    # Same rule as the enforcer: -delete / -exec-family / -f* writers mutate.
+    if any(t in _FIND_MUTATING for t in rest):
+        signals.append(("find-mutating", "destructive", 5))
+    else:
+        signals.append(("find-read", "read", 1))
+
+
+def _sig_sed(verb: str, rest: list[str], segment: str, depth: int,
+             signals: list[_Signal]) -> None:
+    # GNU sed mutates only with -i / --in-place (enforcer parity).
+    in_place = False
+    for tok in rest:
+        if tok.startswith("--"):
+            in_place = in_place or tok.startswith("--in-place")
+        elif tok.startswith("-") and len(tok) > 1:
+            # short-flag cluster: -i, -i.bak, -ni, -Ei all carry the write
+            if "i" in tok[1:].split(".", 1)[0]:
+                in_place = True
+    signals.append(("sed-in-place" if in_place else "sed-read",
+                    "write" if in_place else "read", 3 if in_place else 1))
+
+
+def _sig_sql(verb: str, rest: list[str], segment: str, depth: int,
+             signals: list[_Signal]) -> None:
+    if _SQL_DROP_RE.search(segment):
+        signals.append(("sql-drop", "destructive", 5))
+    elif _SQL_TRUNCATE_RE.search(segment):
+        signals.append(("sql-truncate", "destructive", 5))
+    elif _SQL_DELETE_RE.search(segment):
+        signals.append(("sql-delete", "destructive", 4))
+    elif _SQL_WRITE_RE.search(segment):
+        signals.append(("sql-write", "write", 3))
+    else:
+        signals.append(("sql-read", "read", 1))
+
+
+def _sig_pkg_manager(verb: str, rest: list[str], segment: str, depth: int,
+                     signals: list[_Signal]) -> None:
+    sub, _args = _first_operand(rest)
+    if sub in ("install", "i", "add", "ci", "update", "upgrade", "exec",
+               "test", "run", "build", "start", "create", "dedupe"):
+        # Installs RUN package code (postinstall scripts); tests/builds run
+        # project code. Both are executions.
+        signals.append(("pkg-install", "execute", 3))
+    elif sub == "publish":
+        signals.append(("pkg-publish", "network", 3))
+    elif sub in ("remove", "uninstall", "rm", "purge", "prune"):
+        signals.append(("pkg-remove", "destructive", 3))
+    elif sub in ("list", "ls", "freeze", "show", "info", "view", "search"):
+        signals.append(("pkg-read", "read", 1))
+    else:
+        signals.append(("pkg-other", "execute", 2))
+
+
+def _sig_platform_cli(verb: str, rest: list[str], segment: str, depth: int,
+                      signals: list[_Signal]) -> None:
+    sub, _args = _first_operand(rest)
+    if verb in ("docker", "podman"):
+        if sub in ("run", "build", "exec", "compose", "start", "up"):
+            signals.append(("container-run", "execute", 3))
+        elif sub in ("rm", "rmi", "prune", "system"):
+            signals.append(("container-remove", "destructive", 4))
+        elif sub in ("ps", "images", "logs", "inspect"):
+            signals.append(("container-read", "read", 1))
+        else:
+            signals.append(("container-other", "execute", 2))
+    elif verb == "kubectl":
+        if sub in ("get", "describe", "logs"):
+            signals.append(("kube-read", "read", 1))
+        elif sub in ("delete", "drain"):
+            signals.append(("kube-delete", "destructive", 4))
+        else:
+            signals.append(("kube-apply", "execute", 3))
+    elif verb in ("terraform", "tofu"):
+        if sub == "destroy":
+            signals.append(("iac-destroy", "destructive", 5))
+        elif sub == "apply":
+            signals.append(("iac-apply", "execute", 3))
+        elif sub in ("plan", "show", "output", "state"):
+            signals.append(("iac-read", "read", 1))
+        else:
+            signals.append(("iac-other", "execute", 2))
+    elif verb in ("aws", "gcloud", "az"):
+        low = segment.lower()
+        if "rotate-secret" in low or ("secretsmanager" in low and "rotate" in low):
+            # Secrets rotation invalidates deployed credentials — the blast
+            # radius is a production outage, so it classifies destructive.
+            signals.append(("secrets-rotation", "destructive", 4))
+        elif re.search(r"\bs3\s+(rm|rb|mv)\b", low):
+            signals.append(("cloud-storage-remove", "destructive", 4))
+        else:
+            signals.append(("cloud-api", "network", 2))
+    elif verb == "systemctl":
+        if sub in ("status", "is-active", "is-enabled", "list-units", "show"):
+            signals.append(("service-read", "read", 1))
+        else:
+            signals.append(("service-control", "execute", 3))
+    else:  # go / cargo
+        if sub == "fmt":
+            signals.append(("toolchain-fmt", "write", 2))
+        else:
+            signals.append(("toolchain-run", "execute", 2))
+
+
+def _sig_chmod(verb: str, rest: list[str], segment: str, depth: int,
+               signals: list[_Signal]) -> None:
+    recursive = any(
+        t == "-R" or t == "--recursive"
+        or (t.startswith("-") and not t.startswith("--") and "R" in t)
+        for t in rest
+    )
+    permissive = any(t in ("777", "666", "a+w", "o+w") for t in rest)
+    targets_root = any(t.rstrip("/") == "/" for t in rest if not t.startswith("-"))
+    if recursive and (permissive or targets_root):
+        # `chmod -R 777 /etc`-shaped: broad permission destruction.
+        signals.append(("chmod-recursive-permissive", "destructive", 4))
+    elif recursive:
+        signals.append(("chmod-recursive", "write", 3))
+    else:
+        signals.append(("chmod", "write", 2))
+
+
+def _sig_dd(verb: str, rest: list[str], segment: str, depth: int,
+            signals: list[_Signal]) -> None:
+    of = ""
+    for tok in rest:
+        if tok.startswith("of="):
+            of = tok[3:]
+    if of.startswith("/dev/"):
+        signals.append(("dd-device", "destructive", 5))
+    elif of:
+        signals.append(("dd-file", "write", 3))
+    else:
+        signals.append(("dd-read", "read", 1))
+
+
+def _sig_tar(verb: str, rest: list[str], segment: str, depth: int,
+             signals: list[_Signal]) -> None:
+    if not rest:
+        signals.append(("archive-read", "read", 1))
+        return
+    flags = "".join(t.lstrip("-") for t in rest if t.startswith("-") or t == rest[0])
+    if "x" in flags or "c" in flags:
+        signals.append(("archive-write", "write", 2))
+    else:
+        signals.append(("archive-read", "read", 1))
+
+
+def _sig_rsync(verb: str, rest: list[str], segment: str, depth: int,
+               signals: list[_Signal]) -> None:
+    # A "host:" operand means the wire; otherwise it is a local copy.
+    if any(":" in t and not t.startswith("-") for t in rest):
+        signals.append(("rsync-remote", "network", 3))
+    else:
+        signals.append(("rsync-local", "write", 2))
+
+
+def _sig_simple(weight_class: tuple[str, RiskClass, int]) -> _SignalFn:
+    """Build a constant-signaler for the table-driven trivial verbs."""
+    name, klass, weight = weight_class
+
+    def _emit(verb: str, rest: list[str], segment: str, depth: int,
+              signals: list[_Signal]) -> None:
+        signals.append((name, klass, weight))
+
+    return _emit
+
+
+# Ordered verb dispatch. First match wins; the fallback at the bottom of
+# _classify_segment is a generic execution.
+_VERB_RULES: tuple[tuple[frozenset, _SignalFn], ...] = (
+    (_SHELL_VERBS | {"eval"}, _sig_shell_wrap),
+    (_INTERPRETERS, _sig_interpreter),
+    (frozenset({"git"}), _sig_git),
+    (frozenset({"rm", "unlink", "shred", "rmdir"}), _sig_rm_family),
+    (frozenset({"find"}), _sig_find),
+    (frozenset({"sed"}), _sig_sed),
+    (_SQL_CLIENTS, _sig_sql),
+    (_PKG_MANAGERS, _sig_pkg_manager),
+    (_PLATFORM_CLIS, _sig_platform_cli),
+    (frozenset({"chmod", "chown"}), _sig_chmod),
+    (frozenset({"dd"}), _sig_dd),
+    (frozenset({"tar"}), _sig_tar),
+    (frozenset({"rsync"}), _sig_rsync),
+    (frozenset({"truncate", "wipefs", "fdisk", "sfdisk", "parted", "mkswap"}),
+     _sig_simple(("wipe-device", "destructive", 4))),
+    (frozenset({"curl", "wget", "scp", "sftp", "ssh", "nc", "ncat"}),
+     _sig_simple(("network-call", "network", 3))),
+    (_READ_VERBS, _sig_simple(("read-command", "read", 1))),
+    (_WRITE_VERBS, _sig_simple(("write-command", "write", 2))),
+    (_EXEC_VERBS, _sig_simple(("exec-command", "execute", 2))),
+)
+
+
+def _classify_segment(segment: str, depth: int, signals: list[_Signal]) -> None:
+    # Redirects: operators are matched on quote-blanked text (quoted prose
+    # stays inert) while targets come from the original — see _sig_redirects.
+    _sig_redirects(segment, signals)
+    tokens = _split_tokens(segment)
+    while tokens and _ENV_ASSIGN.match(tokens[0]):
+        tokens = tokens[1:]
+    # Step over launcher prefixes (and their flag/value arguments) so the
+    # REAL verb is judged: `sudo rm -rf /`, `timeout 10 rm -rf x`,
+    # `env FOO=1 rm -rf y`. Same step-over as the self-protect enforcer,
+    # including its known limit: `sudo -u root rm ...` leaves `root` as the
+    # apparent verb (advisory-only cost, documented in the reference doc).
+    while len(tokens) > 1 and _verb_of(tokens[0]) in _LAUNCHERS:
+        tokens = tokens[1:]
+        while tokens and (tokens[0].startswith("-") or tokens[0].isdigit()):
+            tokens = tokens[1:]
+        while tokens and _ENV_ASSIGN.match(tokens[0]):
+            tokens = tokens[1:]
+    if not tokens:
+        return
+    verb = _verb_of(tokens[0])
+    if verb.startswith("mkfs"):
+        signals.append(("mkfs-device", "destructive", 5))
+        return
+    rest = tokens[1:]
+    for names, fn in _VERB_RULES:
+        if verb in names:
+            fn(verb, rest, segment, depth, signals)
+            return
+    # An unknown verb in a shell is a program execution (./script.sh included).
+    signals.append(("shell-command", "execute", 2))
+
+def _split_segments(command: str) -> list[str]:
+    """Split a command into chained segments, ignoring separators inside
+    quotes. Quote interiors are blanked with equal-length space runs so
+    offsets in the blanked copy match the original (this is what keeps the
+    `;` inside `python3 -c "import shutil; shutil.rmtree(x)"` from hiding
+    the rmtree from the interpreter scan — the enforcer chain splits naively
+    and the same evasion shape must not open here)."""
+    blanked = _blank_quotes(command or "")
+    out: list[str] = []
+    last = 0
+    for m in _SEGMENT_SPLIT.finditer(blanked):
+        out.append(command[last:m.start()])
+        last = m.end()
+    out.append(command[last:])
+    return out
+
+
+def _classify_command(command: str, depth: int, signals: list[_Signal]) -> None:
+    for segment in _split_segments(command):
+        segment = segment.strip()
+        if segment:
+            _classify_segment(segment, depth, signals)
+    # A destructive op naming the enforcement control surface (.uap/, .git,
+    # policy tree, proxy env) is the self-targeting evasion the self-protect
+    # enforcer exists for — bump it so it always lands at score 5.
+    if depth == 0 and _PROTECTED_RE.search(command.lower()):
+        if any(klass == "destructive" for _n, klass, _w in signals):
+            signals.append(("protected-target", "destructive", 1))
+
+
+# --- tool-name routing -----------------------------------------------------
+
+_READ_TOOLS = frozenset({
+    "read", "grep", "glob", "ls", "view", "read_file", "list_directory",
+    "search_files", "get_file_info",
+})
+_WRITE_TOOLS = frozenset({
+    "edit", "write", "multiedit", "notebookedit", "create", "create_file",
+    "write_file", "edit_file", "insert", "str_replace_editor",
+})
+_NETWORK_TOOLS = frozenset({
+    "webfetch", "websearch", "web_fetch", "web_search", "fetch", "browse",
+})
+_SHELL_TOOLS = frozenset({
+    "bash", "shell", "execute", "run", "terminal", "exec", "process",
+    "powershell", "cmd", "run_command", "execute_command", "run_terminal_cmd",
+})
+_COMMAND_KEYS = ("command", "cmd", "script", "code")
+_PATH_KEYS = ("file_path", "path", "target", "filename", "filePath")
+
+
+def _tool_family(tool_name: str) -> str:
+    leaf = (tool_name or "").lower().split("__")[-1].replace("-", "_")
+    if leaf in _READ_TOOLS:
+        return "read"
+    if leaf in _WRITE_TOOLS:
+        return "write"
+    if leaf in _NETWORK_TOOLS:
+        return "network"
+    if leaf in _SHELL_TOOLS:
+        return "shell"
+    # MCP-style names (mcp__server__do_thing): substring fallback.
+    if any(k in leaf for k in ("bash", "shell", "terminal", "powershell", "command")):
+        return "shell"
+    if any(k in leaf for k in ("write", "edit", "create", "patch")):
+        return "write"
+    if any(k in leaf for k in ("read", "grep", "glob", "list")):
+        return "read"
+    if any(k in leaf for k in ("fetch", "browse", "search", "http")):
+        return "network"
+    return "unknown"
+
+
+def _extract_command(tool_input: dict) -> str:
+    for key in _COMMAND_KEYS:
+        value = tool_input.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return ""
+
+
+def _extract_path(tool_input: dict) -> str:
+    for key in _PATH_KEYS:
+        value = tool_input.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+    return ""
+
+
+# --- combination -----------------------------------------------------------
+
+
+def _combine(signals: list[_Signal]) -> tuple[RiskClass, int]:
+    """Class = highest total signal weight, ties broken by severity. Score =
+    class base, +1 when the class's evidence is hard (>= _HARD_SIGNAL_WEIGHT),
+    capped at 5. Every point traces to the named signals that produced it."""
+    if not signals:
+        return "read", 1
+    totals: dict[RiskClass, int] = {}
+    for _name, klass, weight in signals:
+        totals[klass] = totals.get(klass, 0) + weight
+    best = max(totals, key=lambda k: (totals[k], -_SEVERITY.index(k)))
+    score = _BASE_SCORE[best] + (1 if totals[best] >= _HARD_SIGNAL_WEIGHT else 0)
+    return best, min(5, score)
+
+
+def _assess(tool_name: str, tool_input: dict) -> tuple[RiskClass, int, list[str]]:
+    """The pure computation: no I/O, no clock. Separated from
+    classify_tool_call so the latency measurement wraps exactly this."""
+    signals: list[_Signal] = []
+    family = _tool_family(tool_name)
+    if family == "shell":
+        command = _extract_command(tool_input)
+        if command:
+            _classify_command(command, 0, signals)
+        else:
+            # An empty command runs nothing.
+            signals.append(("shell-empty", "read", 1))
+    elif family == "write":
+        signals.append(("tool-write", "write", 2))
+        path = _extract_path(tool_input)
+        if path and _PROTECTED_RE.search(path.lower()):
+            signals.append(("protected-target", "write", 3))
+    elif family == "read":
+        signals.append(("tool-read", "read", 1))
+    elif family == "network":
+        signals.append(("tool-network", "network", 3))
+    else:
+        # Unknown tool: assume it can act (advisory pessimism), at the lowest
+        # execution weight. The deterministic enforcers judge it for real.
+        signals.append(("tool-unknown", "execute", 1))
+    risk_class, score = _combine(signals)
+    formatted = [f"{name}:{klass}+{weight}" for name, klass, weight in signals]
+    return risk_class, score, formatted
+
+
+def classify_tool_call(tool_name: str, tool_input: dict) -> RiskAssessment:
+    """Classify one tool call's risk. PURE: no I/O, no global state.
+
+    ``tool_input`` that is not a dict (or missing keys) degrades to the
+    tool-name-only classification — never an exception, never a block.
+    """
+    start = time.perf_counter()
+    if not isinstance(tool_input, dict):
+        tool_input = {}
+    risk_class, score, signals = _assess(str(tool_name or ""), tool_input)
+    latency_ms = (time.perf_counter() - start) * 1000.0
+    return RiskAssessment(
+        risk_class=risk_class,
+        risk_score=score,
+        signals=signals,
+        latency_ms=latency_ms,
+    )