controlzero 1.13.0__tar.gz → 1.13.2__tar.gz

{controlzero-1.13.0 → controlzero-1.13.2}/CHANGELOG.md

@@ -1,5 +1,46 @@
 # Changelog
 
+## 1.13.2 (2026-06-28): kiro-cli 2.10 install crash + cross-adapter hook hardening
+
+### Fixed
+
+- **kiro-cli Windows / non-UTF-8 install crash (Ken Lee report).** `controlzero
+  kiro init` captured kiro-cli's output in text mode using the OS locale codec, so
+  kiro-cli's UTF-8 output crashed the install's subprocess reader thread on
+  non-UTF-8 Windows locales (Korean CP949, Japanese SJIS, Chinese GBK). That crash
+  could leave the governance agent not set as default, so `kiro-cli chat` then ran
+  the built-in default agent ungoverned (no hooks, no audit). All kiro-cli
+  shell-outs now decode as UTF-8 (`errors="replace"`) and never crash the install.
+- **Codex hook-trust requirement surfaced at install.** Codex trust-gates the
+  non-managed `~/.codex/hooks.json` by hash and SKIPS it until trusted; the
+  installer now prints a loud ACTION-REQUIRED step (run `/hooks`, trust the Control
+  Zero hook, re-trust after every upgrade) instead of implying it enforces.
+- **Gemini defensive hooks gate.** The installer writes `hooksConfig.enabled=true`
+  so an admin/older build with hooks gated off does not silently run ungoverned.
+
+### Notes
+
+- kiro-cli 2.10 was verified live to FIRE embedded agent-config `preToolUse` hooks;
+  the canonical tool-name matchers (`execute_bash`/`fs_write`/`fs_read`/`use_aws`)
+  and the `"*"` all-tools token are correct on 2.10 (both new `shell` and legacy
+  `execute_bash` names match).
+
+## 1.13.1 (2026-06-27): shell semantic-class enforcement
+
+### Added
+
+- **Shell semantic-class extractor (#437/#1459).** The enforcer maps a shell
+  command's first meaningful token to a semantic class
+  (`file_write`/`file_delete`/`file_read`/`network`), so a `deny: file_write`
+  rule also blocks shell-mediated file operations (e.g. `Bash(touch x)` ->
+  `file_write`). Additive layer after the per-command action, most-dangerous-wins
+  (`file_delete > network > file_write > file_read`), byte-identical to the Node
+  and Go SDKs (shared `parity-cases.json`, 118 cases). Closes the cross-OS
+  bypass where a denied `Write` was retried as a PowerShell/`cmd`/Unix file
+  write through the Bash tool. Unwraps `sh -c`/`powershell -Command`/`cmd /c`
+  launchers and prefix wrappers; recurses `find -delete`/`find -exec`;
+  whole-line scan for `.NET` method calls and `/dev/tcp/`.
+
 ## 1.13.0 (2026-06-26): policy-condition operator vocab
 
 ### Added

{controlzero-1.13.0 → controlzero-1.13.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: controlzero
-Version: 1.13.0
+Version: 1.13.2
 Summary: AI agent governance: policies, audit, and observability for tool calls. Works locally with no signup.
 Project-URL: Homepage, https://controlzero.ai
 Project-URL: Documentation, https://docs.controlzero.ai

{controlzero-1.13.0 → controlzero-1.13.2}/controlzero/__init__.py

@@ -41,7 +41,7 @@ from controlzero.hitl.grant_protocol import (
 from controlzero.policy_loader import load_policy
 from controlzero.secrets import SecretRef, SecretStr, secret_ref
 
-__version__ = "1.13.0"
+__version__ = "1.13.2"
 
 __all__ = [
     "Client",

{controlzero-1.13.0 → controlzero-1.13.2}/controlzero/_internal/enforcer.py

@@ -470,6 +470,30 @@ class PolicyEvaluator:
                 cls = sql_semantic_class(sql_text)
                 if cls:
                     semantic_action = f"{tool}:{cls}"
+        # Shell semantic-class layer (#437): the SAME additive pattern for
+        # shell-mediated file/network ops. When the tool is the canonical
+        # shell (`Bash`) and no class was provided, derive it from the
+        # command and promote it into the file_write/file_delete/file_read/
+        # network NAMESPACE (`<class>:<class>`) -- NOT `Bash:<class>` --
+        # so a rule `deny: file_write` (normalized `file_write:*`) ALSO
+        # blocks `Bash(touch x)`. Existing `Bash:*` rules are unaffected
+        # because the per-command `action` is always tried first. The
+        # hook-check CLI provides the class via
+        # ``context['action_semantic_class']``; this is the on-the-fly
+        # path for direct ``guard("Bash", args={"command": ...})`` callers.
+        if not semantic_action and tool == "Bash" and args:
+            from controlzero._internal.hook_extractors import shell_semantic_class
+            cmd_text = None
+            if isinstance(args, dict):
+                for _key in ("command", "CommandLine"):
+                    _v = args.get(_key)
+                    if isinstance(_v, str) and _v:
+                        cmd_text = _v
+                        break
+            if cmd_text:
+                cls = shell_semantic_class(cmd_text)
+                if cls:
+                    semantic_action = f"{cls}:{cls}"
         candidate_actions: list[str] = [action]
         if semantic_action and semantic_action != action:
             candidate_actions.append(semantic_action)

{controlzero-1.13.0 → controlzero-1.13.2}/controlzero/_internal/hook_extractors.py

@@ -161,6 +161,97 @@ _SHELL_DANGER_ORDER = (
 )
 _SHELL_DANGER_RANK = {cmd: i for i, cmd in enumerate(_SHELL_DANGER_ORDER)}
 
+# Mapping from shell command basename -> canonical semantic class (#437).
+#
+# A second, portable layer parallel to most_dangerous_shell_command's
+# per-command method. A shell-mediated file or network operation is
+# promoted into the file_write / file_delete / file_read / network tool
+# namespace so a rule written against `file_write` (or `file_write:*`)
+# ALSO blocks `Bash(touch x)` -- not just `Write`. Existing `Bash:*`
+# rules are unaffected: this class is an ADDITIVE candidate the
+# evaluator tries AFTER the per-command action (mirrors how the SQL
+# semantic class layers on top of the per-keyword method).
+#
+# Keys are lowercased; the lookup lowercases the basenamed first token,
+# so PowerShell PascalCase cmdlets (New-Item) and any case mix resolve.
+# Covers Unix coreutils, PowerShell cmdlets + their built-in aliases, and
+# cmd.exe builtins, because on Windows most agents spawn PowerShell/cmd and
+# wrap commands via the Bash tool (the #1459 production bypass:
+# `Bash("New-Item ... | Out-Null; Set-Content ...")`). Shell output
+# redirection (`>`/`>>`) and .NET method calls are detected separately and
+# ALSO classify. DELIBERATELY EXCLUDED to avoid denying common-benign
+# commands: bare `sc` (sc.exe service control), `mkdir`/`md`, `echo`,
+# `dir`/`ls`/`gci`, `set`, and arg-aware verbs (`certutil`, `sed`, `dd`,
+# `robocopy`, `awk`, `tar`, `openssl`, `git`, `rsync`) handled in a follow-up.
+_SHELL_CLASS_MAP = {
+    # ---- file_write: create / append / copy / move-dest / rename ----
+    # Unix
+    "touch": "file_write", "tee": "file_write", "cp": "file_write",
+    "mv": "file_write", "install": "file_write", "ln": "file_write",
+    "truncate": "file_write", "sponge": "file_write", "split": "file_write",
+    "patch": "file_write",
+    # PowerShell cmdlets + aliases (sc EXCLUDED: sc.exe collision)
+    "new-item": "file_write", "ni": "file_write",
+    "set-content": "file_write", "add-content": "file_write", "ac": "file_write",
+    "out-file": "file_write", "tee-object": "file_write",
+    "copy-item": "file_write", "cpi": "file_write",
+    "move-item": "file_write", "mi": "file_write",
+    "rename-item": "file_write", "rni": "file_write",
+    "export-csv": "file_write", "epcsv": "file_write",
+    "export-clixml": "file_write",
+    # cmd.exe
+    "copy": "file_write", "xcopy": "file_write", "move": "file_write",
+    "ren": "file_write", "rename": "file_write", "mklink": "file_write",
+    # ---- file_delete: irreversible removal / truncate-to-empty ----
+    # Unix
+    "rm": "file_delete", "rmdir": "file_delete", "unlink": "file_delete",
+    "shred": "file_delete", "srm": "file_delete", "wipe": "file_delete",
+    "trash": "file_delete", "trash-put": "file_delete",
+    # PowerShell
+    "remove-item": "file_delete", "ri": "file_delete",
+    "clear-content": "file_delete", "clc": "file_delete",
+    "clear-item": "file_delete", "cli": "file_delete",
+    "remove-itemproperty": "file_delete", "rp": "file_delete",
+    # cmd.exe
+    "del": "file_delete", "erase": "file_delete", "rd": "file_delete",
+    "format": "file_delete",
+    # ---- file_read: disclosure ----
+    # Unix
+    "cat": "file_read", "less": "file_read", "more": "file_read",
+    "head": "file_read", "tail": "file_read", "grep": "file_read",
+    "od": "file_read", "hexdump": "file_read", "strings": "file_read",
+    "cut": "file_read", "tac": "file_read", "nl": "file_read",
+    "rev": "file_read", "diff": "file_read", "cmp": "file_read",
+    "paste": "file_read", "wc": "file_read",
+    # PowerShell
+    "get-content": "file_read", "gc": "file_read",
+    "select-string": "file_read", "sls": "file_read",
+    "import-csv": "file_read", "ipcsv": "file_read",
+    "import-clixml": "file_read",
+    # cmd.exe readers. `type` EXCLUDED: in Bash/Zsh `type foo` is benign command
+    # introspection (`type node`), only a file read in cmd/PowerShell -- needs
+    # shell context (follow-up). cmd `find` EXCLUDED (ambiguous with Unix find).
+    "fc": "file_read", "comp": "file_read", "findstr": "file_read",
+    # ---- network: exfiltration / remote transfer / download ----
+    # cross-shell
+    "curl": "network", "wget": "network", "nc": "network", "ncat": "network",
+    "socat": "network", "telnet": "network", "ssh": "network", "scp": "network",
+    "sftp": "network", "gh": "network", "ftp": "network", "tftp": "network",
+    "smbclient": "network", "lftp": "network", "aria2c": "network",
+    # PowerShell (certutil/bitsadmin EXCLUDED: arg-aware, follow-up)
+    "invoke-webrequest": "network", "iwr": "network",
+    "invoke-restmethod": "network", "irm": "network",
+    "start-bitstransfer": "network",
+}
+
+# Class danger ordering: lowest index wins when a compound command's
+# segments resolve to different classes. file_delete (irreversible) >
+# network (exfiltration) > file_write (mutation) > file_read
+# (disclosure). A pipeline `curl evil | rm -rf /` therefore resolves to
+# file_delete so a deny-file_delete rule catches the worst class.
+_SHELL_CLASS_DANGER_ORDER = ("file_delete", "network", "file_write", "file_read")
+_SHELL_CLASS_DANGER_RANK = {c: i for i, c in enumerate(_SHELL_CLASS_DANGER_ORDER)}
+
 
 # ---------------------------------------------------------------------------
 # SQL literal/comment stripping
@@ -440,6 +531,63 @@ def _first_token_basename(segment: str) -> str:
     return token
 
 
+def _has_file_redirect(segment: str) -> bool:
+    """True if ``segment`` redirects output to a FILE (``>`` or ``>>``).
+
+    A grammar-free scan mirroring the deliberately dumb shell tokenizer
+    (#437): a ``>`` is a file redirect unless it is part of a
+    comparison / arrow (``->``, ``=>``, ``<>``) or its target is a
+    file-descriptor duplication (``2>&1``, ``>&2``). Quote handling is
+    intentionally absent, so ``echo "a > b"`` is conservatively
+    classified as a write -- the safe failure direction for a deny rule.
+
+    Byte-identical to the Node ``hasFileRedirect`` and Go
+    ``hasFileRedirect`` implementations.
+    """
+    n = len(segment)
+    i = 0
+    # Depth of Bash test / arithmetic contexts. A ``>`` inside ``[[ ... ]]``
+    # or ``(( ... ))`` is a string/arith comparison, never a file redirect, so
+    # ``[[ "$v" > "1.2" ]]`` must not be classified as a write (would wrongly
+    # deny a legitimate conditional under ``deny: file_write``).
+    test_depth = 0
+    while i < n:
+        two = segment[i:i + 2]
+        if two == "[[" or two == "((":
+            test_depth += 1
+            i += 2
+            continue
+        if two == "]]" or two == "))":
+            if test_depth > 0:
+                test_depth -= 1
+            i += 2
+            continue
+        if segment[i] != ">":
+            i += 1
+            continue
+        if test_depth > 0:
+            i += 1
+            continue
+        prev = segment[i - 1] if i > 0 else ""
+        # ``->``, ``=>``, ``<>`` are operators / dup-source, not a redirect.
+        if prev in ("-", "=", "<"):
+            i += 1
+            continue
+        j = i + 1
+        # Consume the second ``>`` of an append redirect (``>>``).
+        if j < n and segment[j] == ">":
+            j += 1
+        # Skip whitespace between the operator and its target.
+        while j < n and segment[j] in (" ", "\t"):
+            j += 1
+        # A real file redirect has a target that is not ``&`` (which
+        # would be an fd duplication like ``2>&1`` / ``>&2``, not a file).
+        if j < n and segment[j] != "&":
+            return True
+        i = j
+    return False
+
+
 def most_dangerous_shell_command(cmd: str) -> str:
     """Return the most dangerous shell command across every segment.
 
@@ -491,6 +639,312 @@ def most_dangerous_shell_command(cmd: str) -> str:
     return first_segment_token
 
 
+# --- #1459 hardening: bounded wrapper/launcher unwrap ----------------------
+# The extractor still does NOT parse shell grammar. It unwraps a fixed,
+# auditable set of evasion forms so a `deny: file_write` rule is not defeated
+# by `sh -c 'touch x'`, `env touch x`, `sudo rm`, `xargs rm`, `busybox touch`,
+# or `find . -delete`. Forms outside this set (interpreter `-c` with arbitrary
+# code, base64|sh, eval of variables, `-EncodedCommand`) remain documented
+# known limitations. Byte-identical across Python/Node/Go; the adversarial
+# cases are pinned in ``shell_semantic_class_cases`` in ``parity-cases.json``.
+_SHELL_LAUNCHERS = frozenset({"sh", "bash", "zsh", "dash", "ash", "ksh", "su"})
+_POWERSHELL_LAUNCHERS = frozenset({"powershell", "pwsh"})
+_CMD_LAUNCHERS = frozenset({"cmd"})
+# Prefix wrappers consume only flags/operands before the real command. Wrappers
+# that take a POSITIONAL arg first (flock <lockfile>, chroot <dir>, script <file>)
+# are excluded -- they need positional handling and would otherwise misread the
+# arg as the command.
+_SHELL_PREFIX_WRAPPERS = frozenset({
+    "sudo", "doas", "env", "command", "builtin", "exec", "nohup", "setsid",
+    "time", "nice", "ionice", "stdbuf", "timeout", "xargs", "busybox",
+    "watch", "unshare", "nsenter", "parallel",
+})
+_POWERSHELL_CMD_FLAGS = frozenset({"-command", "-c"})
+_CMD_LAUNCHER_FLAGS = frozenset({"/c", "/k"})
+_MAX_SHELL_UNWRAP_DEPTH = 5
+
+# Whole-line substring scan (NOT first-token): PowerShell .NET method calls and
+# bash /dev/tcp sockets bypass the verb layer. Lowercased substring -> class.
+_DOTNET_WRITE_SUBSTRINGS = (
+    "[system.io.file]::writealltext", "[system.io.file]::appendalltext",
+    "[system.io.file]::writeallbytes", "[system.io.file]::create",
+    "[system.io.file]::copy", "[system.io.file]::move",
+    "streamwriter", "filestream",
+)
+_DOTNET_READ_SUBSTRINGS = (
+    "[system.io.file]::readalltext", "[system.io.file]::readallbytes",
+    "[system.io.file]::openread", "streamreader",
+)
+_DOTNET_DELETE_SUBSTRINGS = (
+    "[system.io.file]::delete", "[system.io.directory]::delete",
+)
+_NETWORK_SUBSTRINGS = (
+    ".downloadstring", ".downloadfile", ".uploadfile",
+    "net.webclient", "net.sockets", "/dev/tcp/", "/dev/udp/",
+)
+
+
+def _whole_line_class(cmd_lower: str) -> str:
+    """Most-dangerous class from a lowercased whole-command substring scan,
+    catching .NET method calls (`[System.IO.File]::WriteAllText`, StreamWriter)
+    and bash sockets (`/dev/tcp/`) that are not the first token. ``""`` if none."""
+    best_rank: Optional[int] = None
+    best_class: str = ""
+
+    def consider(cls: str) -> None:
+        nonlocal best_rank, best_class
+        rank = _SHELL_CLASS_DANGER_RANK[cls]
+        if best_rank is None or rank < best_rank:
+            best_rank = rank
+            best_class = cls
+
+    if any(s in cmd_lower for s in _DOTNET_DELETE_SUBSTRINGS):
+        consider("file_delete")
+    if any(s in cmd_lower for s in _NETWORK_SUBSTRINGS):
+        consider("network")
+    if any(s in cmd_lower for s in _DOTNET_WRITE_SUBSTRINGS):
+        consider("file_write")
+    if any(s in cmd_lower for s in _DOTNET_READ_SUBSTRINGS):
+        consider("file_read")
+    return best_class
+
+
+def _cmd_launcher_script(tokens: list) -> Optional[str]:
+    """Script after cmd.exe's ``/c`` or ``/k`` (`cmd /c <command>`), dequoted."""
+    for j, t in enumerate(tokens):
+        if t.lower() in _CMD_LAUNCHER_FLAGS:
+            if j + 1 < len(tokens):
+                return _strip_matched_quotes(" ".join(tokens[j + 1:]))
+            return None
+    return None
+
+
+def _basename_lower(token: str) -> str:
+    idx = token.rfind("/")
+    base = token[idx + 1:] if idx >= 0 else token
+    return base.lower()
+
+
+def _is_env_assignment(token: str) -> bool:
+    """True for a ``VAR=value`` env-assignment prefix token."""
+    eq = token.find("=")
+    if eq <= 0:
+        return False
+    name = token[:eq]
+    if not (name[0].isalpha() or name[0] == "_"):
+        return False
+    return all(c.isalnum() or c == "_" for c in name)
+
+
+# Wrapper option flags that take a SEPARATE operand token, so the operand is
+# skipped too (``sudo -u root rm``, ``xargs -I {} rm``, ``nice -n 10 rm``).
+# Deliberately small + unambiguous: ``-i`` (env ignore-env, no operand) is
+# excluded so ``env -i touch x`` still classifies ``touch``.
+_WRAPPER_VALUE_FLAGS = frozenset({"-u", "--user", "-g", "--group", "-I", "-n", "-p"})
+
+
+def _is_duration_or_number(token: str) -> bool:
+    """A bare number or a duration like ``5`` / ``5s`` (timeout's operand)."""
+    if not token:
+        return False
+    body = token[:-1] if (token[-1] in "smhd" and len(token) >= 2) else token
+    if not body:
+        return False
+    has_digit = False
+    for c in body:
+        if c.isdigit():
+            has_digit = True
+        elif c != ".":
+            return False
+    return has_digit
+
+
+def _is_wrapper_skip_arg(token: str) -> bool:
+    """A token consumed while skipping a prefix wrapper's own args: an option
+    (``-x``), a ``VAR=val`` assignment, or a duration/number (``timeout 5s``)."""
+    if not token:
+        return True
+    if token[0] == "-":
+        return True
+    if _is_env_assignment(token):
+        return True
+    return _is_duration_or_number(token)
+
+
+def _launcher_script(tokens: list) -> Optional[str]:
+    """Script after a shell launcher's ``-c`` flag, including grouped flags
+    like ``-ec`` / ``-lc`` (the rest of the segment, dequoted), or ``None``."""
+    for j, t in enumerate(tokens):
+        low = t.lower()
+        is_c = low == "-c" or (
+            len(low) >= 2
+            and low[0] == "-"
+            and low[1] != "-"
+            and low.endswith("c")
+            and all(ch.isalpha() for ch in low[1:])
+        )
+        if is_c:
+            if j + 1 < len(tokens):
+                return _strip_matched_quotes(" ".join(tokens[j + 1:]))
+            return None
+    return None
+
+
+def _strip_matched_quotes(s: str) -> str:
+    s = s.strip()
+    if len(s) >= 2 and s[0] == s[-1] and s[0] in ("'", '"'):
+        return s[1:-1]
+    return s
+
+
+def _script_after_flag(tokens: list, flags) -> Optional[str]:
+    """The script string following a standalone ``-c`` / ``-Command`` token
+    (the rest of the segment, dequoted), or ``None`` if absent."""
+    for j, t in enumerate(tokens):
+        if t.lower() in flags:
+            if j + 1 < len(tokens):
+                return _strip_matched_quotes(" ".join(tokens[j + 1:]))
+            return None
+    return None
+
+
+def _classify_find(tokens: list, depth: int) -> str:
+    """find(1): ``-delete`` is a delete; ``-exec/-execdir CMD ... ;`` classifies
+    CMD by recursing through the same unwrap (so ``-exec sh -c 'rm x'`` and
+    ``-exec sudo rm`` are caught); a plain search find has no class."""
+    if "-delete" in tokens:
+        return "file_delete"
+    for flag in ("-exec", "-execdir"):
+        if flag in tokens:
+            j = tokens.index(flag)
+            rest = []
+            for t in tokens[j + 1:]:
+                if t in (";", "\\;", "+"):
+                    break
+                rest.append(t)
+            if rest and depth < _MAX_SHELL_UNWRAP_DEPTH:
+                return _classify_shell_segment(" ".join(rest), depth + 1)
+    return ""
+
+
+def _classify_shell_segment(seg: str, depth: int) -> str:
+    """Most-dangerous class for one already-split segment, after unwrapping a
+    bounded set of launchers/prefixes. ``""`` when nothing classifies."""
+    best_rank: Optional[int] = None
+    best_class: str = ""
+
+    def consider(cls: str) -> None:
+        nonlocal best_rank, best_class
+        if not cls:
+            return
+        rank = _SHELL_CLASS_DANGER_RANK[cls]
+        if best_rank is None or rank < best_rank:
+            best_rank = rank
+            best_class = cls
+
+    if _has_file_redirect(seg):
+        consider("file_write")
+
+    tokens = seg.split()
+    i = 0
+    while i < len(tokens) and _is_env_assignment(tokens[i]):
+        i += 1
+    guard = 0
+    while i < len(tokens) and guard < 8:
+        guard += 1
+        base = _basename_lower(tokens[i])
+        if base in _SHELL_LAUNCHERS:
+            sub = _launcher_script(tokens[i:])
+            if sub is not None and depth < _MAX_SHELL_UNWRAP_DEPTH:
+                consider(_shell_semantic_class_inner(sub, depth + 1))
+            break
+        if base in _POWERSHELL_LAUNCHERS:
+            sub = _script_after_flag(tokens[i:], _POWERSHELL_CMD_FLAGS)
+            if sub is not None and depth < _MAX_SHELL_UNWRAP_DEPTH:
+                consider(_shell_semantic_class_inner(sub, depth + 1))
+            break
+        if base in _CMD_LAUNCHERS:
+            sub = _cmd_launcher_script(tokens[i:])
+            if sub is not None and depth < _MAX_SHELL_UNWRAP_DEPTH:
+                consider(_shell_semantic_class_inner(sub, depth + 1))
+            break
+        if base == "find":
+            consider(_classify_find(tokens[i:], depth))
+            break
+        if base in _SHELL_PREFIX_WRAPPERS:
+            i += 1
+            while i < len(tokens) and _is_wrapper_skip_arg(tokens[i]):
+                flag = tokens[i]
+                i += 1
+                # skip the operand of a value-taking flag (sudo -u USER, etc.)
+                if flag in _WRAPPER_VALUE_FLAGS and i < len(tokens) and not tokens[i].startswith("-"):
+                    i += 1
+            continue
+        consider(_SHELL_CLASS_MAP.get(base, ""))
+        break
+
+    return best_class
+
+
+def _shell_semantic_class_inner(cmd: str, depth: int) -> str:
+    if not isinstance(cmd, str) or not cmd.strip():
+        return ""
+    if depth > _MAX_SHELL_UNWRAP_DEPTH:
+        return ""
+    best_rank: Optional[int] = None
+    best_class: str = ""
+
+    def consider(cls: str) -> None:
+        nonlocal best_rank, best_class
+        if not cls:
+            return
+        rank = _SHELL_CLASS_DANGER_RANK[cls]
+        if best_rank is None or rank < best_rank:
+            best_rank = rank
+            best_class = cls
+
+    # Whole-line scan first (.NET method calls / /dev/tcp are not first tokens).
+    consider(_whole_line_class(cmd.lower()))
+    for seg in _split_shell_segments(cmd):
+        consider(_classify_shell_segment(seg, depth))
+    return best_class
+
+
+def shell_semantic_class(cmd: str) -> str:
+    """Return the most-dangerous shell semantic class across every segment.
+
+    Maps shell-mediated file and network operations to one of
+    ``file_write | file_delete | file_read | network`` (or ``""`` when
+    no segment classifies). Closes the #437 bypass where a policy rule
+    ``deny: file_write`` blocked ``Write(...)`` but NOT the equivalent
+    ``Bash(touch x)`` / ``PowerShell(New-Item ...)`` because the shell
+    was treated as an opaque tool.
+
+    Per segment the class is the more-dangerous of:
+
+    - the basenamed, lowercased first command token looked up in
+      ``_SHELL_CLASS_MAP`` (``rm`` -> file_delete, ``curl`` -> network,
+      ``New-Item`` -> file_write), and
+    - ``file_write`` when the segment redirects output to a file
+      (``>`` / ``>>``), so ``cat a > b`` is a write, not a read.
+
+    Compound commands (pipes, ``;``, ``&&``, ``||``, command
+    substitution) reuse :func:`_split_shell_segments` -- the SAME
+    tokenizer :func:`most_dangerous_shell_command` uses -- and the
+    most-dangerous class across all segments wins (file_delete >
+    network > file_write > file_read).
+
+    Empty / non-string / unrecognized input -> ``""``. The shell grammar
+    is deliberately not parsed (no quote stripping, no alias expansion);
+    see the spec README "Known limitations".
+
+    Byte-identical to the Node ``shellSemanticClass`` and Go
+    ``ShellSemanticClass`` implementations; parity is asserted by
+    ``shell_semantic_class_cases`` in ``parity-cases.json``.
+    """
+    return _shell_semantic_class_inner(cmd, 0)
+
+
 def identity(v: str) -> str:
     """Return ``v`` unchanged. Used for browser ``action``."""
     if not isinstance(v, str):
@@ -646,6 +1100,7 @@ __all__ = [
     "most_dangerous_shell_command",
     "most_dangerous_sql_keyword",
     "resolve_canonical_tool",
+    "shell_semantic_class",
     "sql_semantic_class",
     "tool_name_as_method",
 ]