langchain-agentx-python 0.1__py3-none-any.whl

langchain_agentx/tools/bash/prompt.py

@@ -0,0 +1,68 @@
+"""
+tools/bash/prompt.py — BashRuntimeTool 工具名与 prompt 模板
+
+对应 CC prompt.ts 的 getSimplePrompt()（简化版，去掉 sandbox/git 详细指令）。
+纯字符串/常量，无 I/O，无框架依赖，可单独测试。
+"""
+
+from __future__ import annotations
+
+TOOL_NAME = "bash"
+"""工具名，面向模型暴露。"""
+
+DESCRIPTION = "Execute shell commands in a persistent bash session."
+"""简短描述（对应 CC BashTool.description）。"""
+
+# 预期不产生 stdout 的命令（对应 CC BASH_SILENT_COMMANDS）
+SILENT_COMMANDS: frozenset[str] = frozenset({
+    "mv", "cp", "rm", "mkdir", "rmdir", "chmod",
+    "chown", "chgrp", "touch", "ln", "cd",
+    "export", "unset",
+})
+
+
+def get_prompt() -> str:
+    """
+    返回面向模型的完整使用说明（对应 CC getSimplePrompt()）。
+    动态引用 limits 配置，确保 prompt 与实际限制一致。
+    """
+    from .limits import get_bash_limits
+
+    limits = get_bash_limits()
+
+    return (
+        "Executes a given bash command in a persistent shell session and returns its output.\n"
+        "\n"
+        "The working directory persists between commands. "
+        "Shell variable state does NOT persist between separate calls.\n"
+        "\n"
+        "Usage:\n"
+        f"- By default commands timeout after {limits['default_timeout_sec']} seconds "
+        f"(max {limits['max_timeout_sec']} seconds)\n"
+        "- Use the timeout parameter (in seconds) to override the default timeout\n"
+        "- Use run_in_background=true for commands you don't need to wait for "
+        "(dev servers, long builds)\n"
+        "- Commands run in sandbox mode by default; use dangerously_disable_sandbox=true "
+        "only when the runtime explicitly allows bypassing sandbox execution\n"
+        "- Stderr is merged into stdout for a unified terminal-like view\n"
+        "\n"
+        "IMPORTANT: Avoid using this tool to run find/grep/cat/head/tail/sed/awk/echo commands, "
+        "unless the user explicitly instructs it or you have verified that a dedicated tool cannot "
+        "accomplish the task.\n"
+        "\n"
+        "Prefer dedicated tools over this tool when possible:\n"
+        "- Read files: Use the read_file tool (NOT cat/head/tail)\n"
+        "- Search content: Use the grep tool (NOT grep/rg)\n"
+        "- File search: Use the glob tool (NOT find/ls)\n"
+        "- Communication: Output text directly (NOT echo/printf)\n"
+        "\n"
+        "Important restrictions:\n"
+        "- Avoid interactive commands (vim, ssh, python REPL) — they require a TTY\n"
+        f"- Avoid sleep > {limits['sleep_block_threshold_sec']}s — "
+        "use run_in_background=true instead\n"
+        "- Do not retry failing commands in a sleep loop — diagnose the root cause\n"
+        "- When issuing multiple commands:\n"
+        "  - If independent, run multiple bash calls in parallel when appropriate\n"
+        "  - If dependent, use a single bash call and chain with &&\n"
+        "  - Use ';' only when earlier commands may fail\n"
+    )

langchain_agentx/tools/bash/read_only_validation.py

@@ -0,0 +1,589 @@
+"""
+tools/bash/read_only_validation.py — BashRuntimeTool 模块1：只读分类器
+
+职责：
+    将“命令是否可视为只读”从 `security.py` 中解耦出来，形成独立 OOP 协作者。
+
+设计目标：
+    - 对照 CC `readOnlyValidation.ts`，提供 command/flag 级别的只读判断
+    - 大 allowlist + 危险 flag 黑名单 + 组合语义（git stash/remote/config 等）
+    - 轻量平台差异（POSIX / Windows / darwin 常见只读探测命令）
+    - 与 AST / path security 解耦，不直接做 ask / deny，只回答只读语义
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from dataclasses import dataclass
+
+from langchain_agentx.utils.host_platform import (
+    HostPlatform,
+    HostPlatformDetector,
+    default_host_platform_detector,
+)
+
+
+@dataclass(frozen=True)
+class BashReadOnlyClassification:
+    is_read_only: bool
+    reason: str | None = None
+
+
+class BashReadOnlyClassifier:
+    """命令级只读语义分类器（P2：规模 + 危险 flag + 组合语义 + 平台差异）。"""
+
+    def __init__(self, *, host_detector: HostPlatformDetector | None = None) -> None:
+        self._host = host_detector or default_host_platform_detector()
+
+    # ------------------------------------------------------------------
+    # 大 allowlist：常见只读/观测类命令（不含必然写盘的工具如 tee/dd of=）
+    # ------------------------------------------------------------------
+    _READ_ONLY_COMMANDS = frozenset({
+        "ls", "dir", "cat", "head", "tail", "wc", "stat", "file",
+        "echo", "printf", "pwd", "env", "which", "whereis", "type", "where",
+        "grep", "egrep", "fgrep", "rg", "ag", "ack", "find",
+        "ps", "top", "htop", "df", "du", "free", "uptime", "date", "uname", "hostname",
+        "id", "whoami", "groups", "who", "w", "last", "finger",
+        "diff", "cmp", "comm", "join", "paste", "column",
+        "md5sum", "sha256sum", "sha512sum", "sha1sum", "shasum", "cksum", "sum",
+        "xxd", "hexdump", "od", "strings", "nm", "objdump", "readelf",
+        "lsof", "netstat", "ss", "ip", "ifconfig", "route",
+        "zipinfo",
+        "nl", "cut", "tr", "uniq", "expand", "unexpand", "fold", "fmt", "pr", "rev", "tac",
+        "look", "basename", "dirname", "readlink", "realpath",
+        "true", "false", "test", "expr", "seq",
+        "iconv", "locale", "locales", "getconf",
+        "sw_vers", "sysctl", "system_profiler", "pbpaste",
+        "ver",
+        "less", "more", "most", "bat", "jq", "yq", "awk", "mawk", "gawk",
+        "bc", "factor", "units", "getent",
+        "vmstat", "iostat", "mpstat", "sar", "dmesg", "tload",
+        "apropos", "whatis", "man",
+    })
+
+    _READ_ONLY_GIT = frozenset({
+        "log", "status", "diff", "show", "describe", "blame", "shortlog",
+        "whatchanged", "name-rev", "verify-tag", "rev-list", "ls-files", "ls-tree",
+    })
+
+    _FIND_WRITE_FLAGS = frozenset({
+        "-delete", "-exec", "-execdir", "-ok", "-okdir", "-quit",
+        "-fprint", "-fprintf", "-fls", "-ls", "-print0",
+    })
+    _UNZIP_READ_ONLY_FLAGS = frozenset({"l", "t", "p", "v", "Z"})
+    _RAR_READ_ONLY_ACTIONS = frozenset({"l", "lb", "lt", "t", "p", "v"})
+    _SEVEN_Z_READ_ONLY_ACTIONS = frozenset({"l", "t", "i"})
+    _STDOUT_FLAGS = frozenset({"-c", "--stdout", "--to-stdout"})
+    _ZIPNOTE_WRITE_FLAGS = frozenset({"-w", "--write"})
+
+    _SORT_WRITE_FLAGS = frozenset({"-o", "--output"})
+
+    _GIT_MUTATING_SUBCOMMANDS = frozenset({
+        "add", "apply", "am", "archive", "bisect", "checkout", "cherry-pick",
+        "clean", "clone", "commit", "fetch", "gc", "init", "merge", "mv",
+        "pull", "push", "rebase", "reset", "restore", "revert", "rm", "switch",
+        "worktree", "update-ref", "notes", "sparse-checkout", "submodule",
+    })
+
+    _GIT_READONLY_BUT_MUTATING_FLAGS = {
+        "tag": frozenset({"-d", "--delete", "-f", "--force"}),
+        "branch": frozenset({"-d", "-D", "-m", "-M", "-c", "-C", "--delete", "--move", "--copy"}),
+        "stash": frozenset({"push", "pop", "apply", "drop", "clear", "store", "branch", "save"}),
+    }
+
+    _STASH_READ_ONLY_VERBS = frozenset({"show", "list", "diff"})
+
+    _DOCKER_READ_ONLY = frozenset({
+        "ps", "images", "inspect", "version", "info", "top", "stats", "events",
+        "history", "logs",
+    })
+    _DOCKER_MUTATING = frozenset({
+        "run", "exec", "cp", "build", "pull", "push", "rm", "rmi", "create", "start",
+        "stop", "kill", "restart", "commit", "import", "load", "save", "tag", "update",
+        "volume", "network", "system",
+    })
+
+    _KUBECTL_READ_ONLY = frozenset({
+        "get", "describe", "explain", "version", "api-resources", "api-versions",
+        "cluster-info", "logs", "top", "auth", "config",
+    })
+    _KUBECTL_MUTATING = frozenset({
+        "apply", "create", "delete", "patch", "replace", "run", "expose", "scale",
+        "rollout", "label", "annotate", "cordon", "uncordon", "drain", "taint",
+        "port-forward", "attach", "exec", "cp",
+    })
+
+    def _platform_readonly_extras(self) -> frozenset[str]:
+        pf = self._platform_family()
+        if pf == "win32":
+            return frozenset({"findstr", "fc", "where"})
+        if pf == "darwin":
+            return frozenset({"vm_stat"})
+        return frozenset()
+
+    def classify(self, command: str) -> BashReadOnlyClassification:
+        if self._shell_compound_or_pipeline(command):
+            return BashReadOnlyClassification(False, "shell_compound_or_pipeline")
+
+        tokens = self._split(command)
+        if not tokens:
+            return BashReadOnlyClassification(False, "empty_command")
+
+        base = self._basename(tokens[0])
+
+        if base in {"cmd", "cmd.exe", "powershell", "powershell.exe", "pwsh", "pwsh.exe"}:
+            return BashReadOnlyClassification(False, f"{base}_shell_not_classified")
+
+        if base == "git":
+            return self._classify_git(tokens)
+
+        if base == "sort":
+            if self._tokens_contain_any_flag(tokens, self._SORT_WRITE_FLAGS):
+                return BashReadOnlyClassification(False, "sort_output_file_flag")
+            return BashReadOnlyClassification(True, "sort_stdout")
+
+        if base == "tee":
+            return BashReadOnlyClassification(False, "tee_writes")
+
+        if base == "dd":
+            if self._dd_has_output_file(command):
+                return BashReadOnlyClassification(False, "dd_output_file")
+            return BashReadOnlyClassification(True, "dd_stdout_only")
+
+        if base in {"tar", "bsdtar"}:
+            return BashReadOnlyClassification(self._has_tar_list_mode(tokens), "tar_mode")
+
+        if base == "unzip":
+            return BashReadOnlyClassification(self._has_unzip_read_only_mode(tokens), "unzip_mode")
+
+        if base in {"7z", "7za", "7zr"}:
+            return BashReadOnlyClassification(
+                self._7z_action(tokens) in self._SEVEN_Z_READ_ONLY_ACTIONS,
+                "7z_action",
+            )
+
+        if base == "jar":
+            return BashReadOnlyClassification(self._jar_mode_is_read_only(tokens), "jar_mode")
+
+        if base in {"rar", "unrar"}:
+            action = tokens[1].lower() if len(tokens) > 1 else ""
+            return BashReadOnlyClassification(action in self._RAR_READ_ONLY_ACTIONS, "rar_action")
+
+        if base == "zipnote":
+            has_write = any(token in self._ZIPNOTE_WRITE_FLAGS for token in tokens[1:])
+            return BashReadOnlyClassification(not has_write, "zipnote_mode")
+
+        if base in {"gzip", "gunzip", "xz", "unxz", "bzip2", "bunzip2", "zstd", "unzstd", "lz4"}:
+            return BashReadOnlyClassification(self._has_stdout_mode(tokens), f"{base}_stdout")
+
+        if base in {"curl", "wget"}:
+            return self._classify_http_fetch(tokens, base)
+
+        if base == "cpio":
+            return BashReadOnlyClassification(self._cpio_list_mode(tokens), "cpio_mode")
+
+        if base == "docker":
+            return self._classify_docker(tokens)
+
+        if base == "kustomize":
+            return self._classify_kustomize(tokens)
+        if base in {"kubectl", "oc"}:
+            return self._classify_kubectl(tokens, base)
+
+        if base == "sed":
+            return self._classify_sed(tokens)
+
+        if base in {"awk", "mawk", "gawk"}:
+            return self._classify_awk(tokens)
+
+        if base in {"perl", "perl5"}:
+            return self._classify_perl(tokens)
+
+        if base in self._READ_ONLY_COMMANDS or base in self._platform_readonly_extras():
+            if base == "find" and any(token in self._FIND_WRITE_FLAGS for token in tokens[1:]):
+                return BashReadOnlyClassification(False, "find_write_flag")
+            return BashReadOnlyClassification(True, f"{base}_readonly")
+
+        return BashReadOnlyClassification(False, f"{base}_unknown")
+
+    @staticmethod
+    def _shell_compound_or_pipeline(command: str) -> bool:
+        """单 segment 内的 `|` / `&&` / `||` 保守视为非只读（不含 `;`，避免 awk/sed 脚本误判）。"""
+        if "|" in command:
+            return True
+        if "&&" in command or "||" in command:
+            return True
+        return False
+
+    def _classify_kustomize(self, tokens: list[str]) -> BashReadOnlyClassification:
+        if len(tokens) > 1 and tokens[1].lower() == "build":
+            return BashReadOnlyClassification(True, "kustomize_build")
+        return BashReadOnlyClassification(False, "kustomize_not_classified")
+
+    def _classify_sed(self, tokens: list[str]) -> BashReadOnlyClassification:
+        if self._sed_has_inplace(tokens):
+            return BashReadOnlyClassification(False, "sed_inplace")
+        return BashReadOnlyClassification(True, "sed_stdout")
+
+    def _sed_has_inplace(self, tokens: list[str]) -> bool:
+        for i, t in enumerate(tokens[1:], start=1):
+            if t == "--in-place":
+                return True
+            if t.startswith("-i") and t != "-i":
+                return True
+            if t == "-i":
+                return True
+            if t.startswith("-i") and len(t) > 2:
+                return True
+        return False
+
+    def _classify_awk(self, tokens: list[str]) -> BashReadOnlyClassification:
+        args = tokens[1:]
+        if self._awk_inplace_gnu(args):
+            return BashReadOnlyClassification(False, "awk_inplace")
+        return BashReadOnlyClassification(True, "awk_stdout")
+
+    @staticmethod
+    def _awk_inplace_gnu(args: list[str]) -> bool:
+        for i, a in enumerate(args):
+            if a == "-i" and i + 1 < len(args) and args[i + 1] == "inplace":
+                return True
+        return False
+
+    def _classify_perl(self, tokens: list[str]) -> BashReadOnlyClassification:
+        for t in tokens[1:]:
+            if t == "-i" or (t.startswith("-i") and len(t) > 2):
+                return BashReadOnlyClassification(False, "perl_inplace")
+        return BashReadOnlyClassification(True, "perl_stdout")
+
+    def _cpio_list_mode(self, tokens: list[str]) -> bool:
+        """仅列出归档内容（-it / -t + -F archive）视为只读；extract/create/pass 非只读。"""
+        has_t = False
+        has_i = False
+        has_o = False
+        has_p = False
+        for t in tokens[1:]:
+            if t in ("-t", "--list"):
+                has_t = True
+                continue
+            if t.startswith("-") and not t.startswith("--"):
+                body = t[1:]
+                if "t" in body:
+                    has_t = True
+                if "i" in body:
+                    has_i = True
+                if "o" in body:
+                    has_o = True
+                if "p" in body:
+                    has_p = True
+        if has_o or has_p:
+            return False
+        if has_i and has_t:
+            return True
+        return False
+
+    def _classify_docker(self, tokens: list[str]) -> BashReadOnlyClassification:
+        sub, rest = self._docker_primary_and_rest(tokens)
+        if not sub:
+            return BashReadOnlyClassification(False, "docker_empty")
+        if sub in {"compose", "buildx"}:
+            return BashReadOnlyClassification(False, f"docker_{sub}_not_classified")
+        if sub in self._DOCKER_NETWORK_VOLUME_SYSTEM:
+            return self._classify_docker_plugin(sub, rest)
+        if sub in self._DOCKER_READ_ONLY:
+            return BashReadOnlyClassification(True, f"docker_{sub}_readonly")
+        if sub in self._DOCKER_MUTATING:
+            return BashReadOnlyClassification(False, f"docker_{sub}_mutating")
+        return BashReadOnlyClassification(False, "docker_unknown")
+
+    _DOCKER_NETWORK_VOLUME_SYSTEM = frozenset({"network", "volume", "system"})
+
+    def _classify_docker_plugin(self, plugin: str, rest: list[str]) -> BashReadOnlyClassification:
+        verb = self._git_first_non_flag(rest).lower()
+        if plugin == "network" and verb in {"ls", "list", "inspect"}:
+            return BashReadOnlyClassification(True, "docker_network_readonly")
+        if plugin == "volume" and verb in {"ls", "list", "inspect"}:
+            return BashReadOnlyClassification(True, "docker_volume_readonly")
+        if plugin == "system" and verb in {"df", "info", "events", "prune"}:
+            if verb == "prune":
+                return BashReadOnlyClassification(False, "docker_system_prune")
+            return BashReadOnlyClassification(True, f"docker_system_{verb}")
+        return BashReadOnlyClassification(False, f"docker_{plugin}_unknown")
+
+    @staticmethod
+    def _docker_primary_and_rest(tokens: list[str]) -> tuple[str, list[str]]:
+        i = 1
+        n = len(tokens)
+        while i < n:
+            t = tokens[i]
+            if t in ("-H", "--host", "-c", "--context", "--config") and i + 1 < n:
+                i += 2
+                continue
+            if t.startswith("-"):
+                i += 1
+                continue
+            return t.lower(), tokens[i + 1 :]
+        return "", []
+
+    def _classify_kubectl(self, tokens: list[str], base: str) -> BashReadOnlyClassification:
+        verb, rest = self._kubectl_verb_and_rest(tokens)
+        if not verb:
+            return BashReadOnlyClassification(False, f"{base}_empty")
+        if verb == "config":
+            return self._classify_kubectl_config(rest)
+        if verb in self._KUBECTL_READ_ONLY:
+            return BashReadOnlyClassification(True, f"{base}_{verb}_readonly")
+        if verb in self._KUBECTL_MUTATING:
+            return BashReadOnlyClassification(False, f"{base}_{verb}_mutating")
+        return BashReadOnlyClassification(False, f"{base}_{verb}_unknown")
+
+    def _classify_kubectl_config(self, rest: list[str]) -> BashReadOnlyClassification:
+        """kubectl config view|get-contexts 只读；set-credentials/set-context 等变更。"""
+        sub = self._git_first_non_flag(rest).lower()
+        if sub in {"view", "get-contexts", "get-clusters", "current-context"}:
+            return BashReadOnlyClassification(True, "kubectl_config_readonly")
+        if sub in {
+            "set", "use-context", "rename-context", "delete-context",
+            "set-cluster", "set-credentials", "unset",
+        }:
+            return BashReadOnlyClassification(False, "kubectl_config_mutating")
+        if not sub:
+            return BashReadOnlyClassification(False, "kubectl_config_empty")
+        return BashReadOnlyClassification(False, "kubectl_config_unknown")
+
+    @staticmethod
+    def _kubectl_verb_and_rest(tokens: list[str]) -> tuple[str, list[str]]:
+        i = 1
+        n = len(tokens)
+        while i < n:
+            t = tokens[i]
+            if not t.startswith("-"):
+                return t.lower(), tokens[i + 1 :]
+            if t in (
+                "-n", "--namespace", "-o", "--output", "--kubeconfig", "--context",
+                "--server", "-f", "--filename", "-l", "--selector",
+            ) and i + 1 < n:
+                i += 2
+                continue
+            if t == "--":
+                i += 1
+                continue
+            i += 1
+        return "", []
+
+    def _git_skip_global_options(self, tokens: list[str], start: int) -> int:
+        i = start
+        while i < len(tokens):
+            t = tokens[i]
+            if t in ("-C", "--git-dir", "--work-tree") and i + 1 < len(tokens):
+                i += 2
+                continue
+            if t.startswith("-"):
+                i += 1
+                continue
+            break
+        return i
+
+    def _git_primary_and_rest(self, tokens: list[str]) -> tuple[str, list[str]]:
+        i = self._git_skip_global_options(tokens, 1)
+        if i >= len(tokens):
+            return "", []
+        return tokens[i], tokens[i + 1 :]
+
+    @staticmethod
+    def _git_first_non_flag(rest: list[str]) -> str:
+        for t in rest:
+            if not t.startswith("-"):
+                return t
+        return ""
+
+    def _classify_git(self, tokens: list[str]) -> BashReadOnlyClassification:
+        subcommand, rest = self._git_primary_and_rest(tokens)
+        if not subcommand:
+            return BashReadOnlyClassification(False, "git_empty")
+
+        if subcommand == "config":
+            return self._classify_git_config(rest)
+
+        if subcommand in self._GIT_MUTATING_SUBCOMMANDS:
+            return BashReadOnlyClassification(False, f"git_{subcommand}_mutating")
+
+        if subcommand == "stash":
+            if any(
+                x in rest
+                for x in ("-p", "--patch", "-u", "--include-untracked", "-a", "--all", "-m", "--message")
+            ):
+                return BashReadOnlyClassification(False, "git_stash_create_flags")
+            verb = self._git_first_non_flag(rest)
+            if verb in self._GIT_READONLY_BUT_MUTATING_FLAGS["stash"]:
+                return BashReadOnlyClassification(False, "git_stash_mutating")
+            if verb in self._STASH_READ_ONLY_VERBS:
+                return BashReadOnlyClassification(True, "git_stash_readonly")
+            if not verb:
+                return BashReadOnlyClassification(True, "git_stash_list_default")
+            return BashReadOnlyClassification(False, "git_stash_unknown")
+
+        if subcommand == "remote":
+            verb = self._git_first_non_flag(rest)
+            mutating = {"add", "remove", "rename", "set-url", "set-branches", "prune", "update"}
+            if verb in mutating:
+                return BashReadOnlyClassification(False, "git_remote_mutating")
+            return BashReadOnlyClassification(True, "git_remote_readonly")
+
+        if subcommand == "branch":
+            if self._git_scan_mutating_flags("branch", rest):
+                return BashReadOnlyClassification(False, "git_branch_mutating_flag")
+            return BashReadOnlyClassification(True, "git_branch_list")
+
+        if subcommand == "tag":
+            if self._git_scan_mutating_flags("tag", rest):
+                return BashReadOnlyClassification(False, "git_tag_mutating_flag")
+            return BashReadOnlyClassification(True, "git_tag_list")
+
+        if self._git_scan_mutating_flags(subcommand, rest):
+            return BashReadOnlyClassification(False, f"git_{subcommand}_mutating_flag")
+
+        is_ro = subcommand in self._READ_ONLY_GIT
+        return BashReadOnlyClassification(is_ro, f"git_{subcommand}")
+
+    def _classify_git_config(self, rest: list[str]) -> BashReadOnlyClassification:
+        if any(
+            x in rest
+            for x in (
+                "--add", "--unset", "--unset-all", "--replace-all",
+                "--remove-section", "--rename-section",
+            )
+        ):
+            return BashReadOnlyClassification(False, "git_config_mutating_flag")
+        if "--list" in rest or "-l" in rest:
+            return BashReadOnlyClassification(True, "git_config_list")
+        if any(x in rest for x in ("--get", "--get-all", "--get-regexp", "--get-urlmatch")):
+            return BashReadOnlyClassification(True, "git_config_get")
+        # 位置参数：仅 section.key → 查询；存在赋值（两段子键值或含 =）→ 变更
+        pos: list[str] = []
+        i = 0
+        while i < len(rest):
+            t = rest[i]
+            if t.startswith("-"):
+                if t in ("--file", "-f") and i + 1 < len(rest):
+                    i += 2
+                    continue
+                i += 1
+                continue
+            pos.append(t)
+            i += 1
+        if len(pos) >= 2:
+            return BashReadOnlyClassification(False, "git_config_set_value")
+        if len(pos) == 1 and "=" in pos[0]:
+            return BashReadOnlyClassification(False, "git_config_set_inline")
+        if len(pos) == 1:
+            return BashReadOnlyClassification(True, "git_config_get_key")
+        return BashReadOnlyClassification(False, "git_config_ambiguous")
+
+    def _git_scan_mutating_flags(self, subcommand: str, rest: list[str]) -> bool:
+        rules = self._GIT_READONLY_BUT_MUTATING_FLAGS.get(subcommand)
+        if not rules:
+            return False
+        return any(tok in rules for tok in rest)
+
+    def _classify_http_fetch(self, tokens: list[str], base: str) -> BashReadOnlyClassification:
+        if base == "curl":
+            if self._tokens_contain_any_flag(
+                tokens,
+                {"-o", "--output", "-O", "--remote-name", "--remote-name-all"},
+            ):
+                return BashReadOnlyClassification(False, "curl_local_write")
+            return BashReadOnlyClassification(True, "curl_stdout")
+        if base == "wget":
+            if any(t in tokens for t in ("-O", "--output-document")):
+                doc = self._wget_output_document(tokens)
+                if doc and doc != "-":
+                    return BashReadOnlyClassification(False, "wget_local_write")
+            if "-P" in tokens or "--directory-prefix" in tokens:
+                return BashReadOnlyClassification(False, "wget_local_write")
+            joined = " ".join(tokens)
+            if "-O-" in joined or any(
+                i < len(tokens) - 1 and tokens[i] == "-O" and tokens[i + 1] == "-"
+                for i in range(len(tokens))
+            ):
+                return BashReadOnlyClassification(True, "wget_stdout")
+            return BashReadOnlyClassification(False, "wget_default_file")
+
+        return BashReadOnlyClassification(False, "http_fetch_unknown")
+
+    def _wget_output_document(self, tokens: list[str]) -> str | None:
+        for i, t in enumerate(tokens):
+            if t in ("-O", "--output-document") and i + 1 < len(tokens):
+                return tokens[i + 1]
+        return None
+
+    @staticmethod
+    def _dd_has_output_file(command: str) -> bool:
+        return bool(re.search(r"(?:^|\s)of=", command))
+
+    @staticmethod
+    def _tokens_contain_any_flag(tokens: list[str], flags: set[str]) -> bool:
+        for t in tokens[1:]:
+            if t in flags:
+                return True
+            if t.startswith("-") and not t.startswith("--"):
+                for fl in flags:
+                    if fl.startswith("-") and len(fl) == 2 and fl[1] in t[1:]:
+                        return True
+        return False
+
+    @staticmethod
+    def _split(command: str) -> list[str]:
+        try:
+            return shlex.split(command)
+        except ValueError:
+            return command.split()
+
+    @staticmethod
+    def _basename(token: str) -> str:
+        return token.rsplit("/", 1)[-1]
+
+    @staticmethod
+    def _has_tar_list_mode(tokens: list[str]) -> bool:
+        for token in tokens[1:]:
+            if token == "--list":
+                return True
+            if token.startswith("-") and not token.startswith("--") and "t" in token and "x" not in token:
+                return True
+        return False
+
+    def _has_unzip_read_only_mode(self, tokens: list[str]) -> bool:
+        for token in tokens[1:]:
+            if token.startswith("--"):
+                continue
+            if token.startswith("-") and any(flag in token for flag in self._UNZIP_READ_ONLY_FLAGS):
+                return True
+        return False
+
+    @staticmethod
+    def _7z_action(tokens: list[str]) -> str:
+        for token in tokens[1:]:
+            if token.startswith("-"):
+                continue
+            return token.lower()
+        return ""
+
+    @staticmethod
+    def _jar_mode_is_read_only(tokens: list[str]) -> bool:
+        if len(tokens) < 2:
+            return False
+        mode_token = tokens[1].lstrip("-")
+        return "t" in mode_token and "x" not in mode_token and "c" not in mode_token and "u" not in mode_token
+
+    def _has_stdout_mode(self, tokens: list[str]) -> bool:
+        return any(token in self._STDOUT_FLAGS for token in tokens[1:])
+
+    def _platform_family(self) -> str:
+        """与历史 ``sys.platform`` 三分支对齐；WSL/Linux 归入 posix extras。"""
+        kind = self._host.current()
+        if kind == HostPlatform.WINDOWS:
+            return "win32"
+        if kind == HostPlatform.MACOS:
+            return "darwin"
+        return "posix"