@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-ops/hooks/modules/security/mutative_verbs.py

@@ -0,0 +1,1131 @@
+"""
+Mutative verb detector for shell commands.
+
+Simplified three-category pipeline:
+  blocked_commands.py  ->  BLOCKED (exit 2, permanently denied)
+  mutative_verbs.py    ->  MUTATIVE (needs user approval via nonce)
+  everything else      ->  SAFE (auto-approved by elimination)
+
+This module detects MUTATIVE commands by scanning tokens for known verb patterns,
+dangerous flags, and command aliases. If a command is not blocked and not mutative,
+it is safe by elimination -- no allowlist needed.
+
+Categories retained internally for verb classification:
+- MUTATIVE: ALL state-modifying verbs (approvable via nonce workflow)
+- SIMULATION: plan, diff, preview, template, validate, lint, etc.
+- READ_ONLY: get, list, describe, show, logs, status, etc.
+"""
+
+import functools
+import logging
+from dataclasses import dataclass
+from typing import Dict, FrozenSet, List, Tuple, Union
+
+from .approval_messages import build_t3_approval_instructions
+from .command_semantics import analyze_command
+
+try:
+    from .blocked_commands import is_blocked_command as _is_blocked_command
+except ImportError:
+    _is_blocked_command = None
+    logging.getLogger(__name__).warning(
+        "blocked_commands.is_blocked_command not importable; "
+        "inline code Layer 1 (shell extraction) disabled"
+    )
+
+logger = logging.getLogger(__name__)
+
+
+# ============================================================================
+# Category Constants
+# ============================================================================
+
+CATEGORY_MUTATIVE = "MUTATIVE"
+CATEGORY_SIMULATION = "SIMULATION"
+CATEGORY_READ_ONLY = "READ_ONLY"
+CATEGORY_UNKNOWN = "UNKNOWN"
+
+
+# ============================================================================
+# MutativeResult
+# ============================================================================
+
+@dataclass(frozen=True)
+class MutativeResult:
+    """Structured result of mutative verb detection.
+
+    Attributes:
+        is_mutative: Whether the command is classified as mutative (T3).
+        category: Verb category: CATEGORY_MUTATIVE, CATEGORY_SIMULATION,
+            CATEGORY_READ_ONLY, or CATEGORY_UNKNOWN.
+        verb: The extracted verb (e.g., "delete", "apply", "get").
+        dangerous_flags: Tuple of flags that escalate the danger level.
+        cli_family: Lightweight CLI family hint (e.g., "k8s", "cloud", "git").
+        confidence: Confidence level: "high", "medium", or "low".
+        reason: Human-readable explanation of the classification.
+    """
+    is_mutative: bool = False
+    category: str = CATEGORY_UNKNOWN
+    verb: str = ""
+    dangerous_flags: Tuple[str, ...] = ()
+    cli_family: str = "unknown"
+    confidence: str = "low"
+    reason: str = ""
+
+
+
+# ============================================================================
+# Verb Taxonomy Constants
+# ============================================================================
+
+MUTATIVE_VERBS: FrozenSet[str] = frozenset({
+    # Creation / addition
+    # NOTE: "add" removed -- safe by elimination (e.g., git add is local-only)
+    "apply", "create", "put", "insert", "register",
+    # Modification
+    "update", "patch", "set", "modify", "edit", "configure",
+    "replace", "overwrite", "write",
+    # Deployment / packaging
+    # NOTE: "release" removed -- it is a CLI subcommand group noun in `gh release`,
+    # `glab release`, etc. The actual mutative actions (create, delete, edit, upload)
+    # are already in MUTATIVE_VERBS. Keeping "release" here causes false positives on
+    # `gh release view` and any command with "release" as an argument string.
+    "deploy", "install", "upgrade", "downgrade", "publish", "promote",
+    # Scaling
+    "scale", "resize", "autoscale",
+    # Lifecycle
+    "start", "restart", "reboot", "reload", "refresh", "resume",
+    "uncordon", "unsuspend", "enable", "disable", "suspend", "pause",
+    "stop", "shutdown", "halt", "abort",
+    # Movement / transfer
+    "move", "rename", "copy", "sync",
+    "import", "export", "migrate", "transfer",
+    # Attachment
+    # NOTE: "link" removed -- false positive in shell variable names (e.g., "for link in ...").
+    #       The `ln` command is already covered as a COMMAND_ALIAS.
+    "attach", "bind", "connect", "mount",
+    # Execution
+    # NOTE: "run" removed -- safe by elimination (e.g., docker run is common dev workflow)
+    "exec", "execute", "invoke", "trigger", "send", "reply",
+    # Git operations
+    # NOTE: "stash" removed -- safe by elimination (local-only operation)
+    # NOTE: "commit" removed -- local-only operation, trust system
+    "push", "merge", "rebase",
+    "rollback",
+    # Access control
+    "grant", "assign", "revoke",
+    # Reconciliation
+    "reconcile", "rsync",
+    # Deletion / removal (approvable via nonce -- blocked_commands.py catches
+    # the truly destructive patterns like "delete namespace", "delete-vpc", etc.)
+    "delete", "destroy", "remove", "drop", "purge", "wipe", "clean",
+    "trash", "shred", "srm",
+    "truncate", "kill", "terminate", "uninstall", "unpublish",
+    "drain", "evict", "cordon", "deregister", "detach",
+    "disconnect", "unbind", "force-delete", "force-remove", "erase",
+    # Collaboration (GitHub/GitLab CLI)
+    "comment", "label", "annotate", "approve", "close", "reopen", "tag",
+    # Helm-specific
+    "uninstall",
+    # HTTP methods (e.g., glab api -X POST, gh api -X DELETE)
+    "post", "put", "patch",
+})
+
+SIMULATION_VERBS: FrozenSet[str] = frozenset({
+    "plan", "diff", "preview", "template", "render", "simulate",
+    "test", "check", "verify", "lint", "validate", "fmt", "format", "audit",
+})
+
+READ_ONLY_VERBS: FrozenSet[str] = frozenset({
+    "get", "list", "describe", "show", "read", "view", "inspect",
+    "info", "status", "log", "logs", "tail", "head",
+    "search", "find", "query", "scan", "fetch", "download",
+    "version", "help", "whoami", "which", "explain",
+    "top", "stat", "history", "blame", "tree", "shortlog", "reflog",
+    "env", "auth", "config", "cluster-info", "api-resources", "ls",
+    # Compound subcommands that look mutative after hyphen-split but are read-only
+    "merge-base",
+})
+
+
+# ============================================================================
+# Compound Read-Only Subcommands
+# ============================================================================
+# Full subcommand tokens that must be matched BEFORE the hyphen-split logic.
+# Without this, "merge-base" would be split to "merge" and flagged as MUTATIVE.
+
+COMPOUND_READ_ONLY_SUBCOMMANDS: FrozenSet[str] = frozenset({
+    "merge-base",
+})
+
+
+# ============================================================================
+# Git Local-Only Subcommands (early-exit guard)
+# ============================================================================
+# Git subcommands that NEVER mutate remote state.  When the base command is
+# "git" and the first non-flag token is one of these, short-circuit to
+# non-mutative.  This prevents message body text (after -m) from leaking
+# into the verb scanner and triggering false positives on words like
+# "update", "create", "deploy" inside commit messages.
+#
+# NOT included here (intentionally left to the verb scanner):
+#   push    -- mutates remote
+#   merge   -- in MUTATIVE_VERBS (local but destructive merge commit)
+#   rebase  -- in MUTATIVE_VERBS (rewrites history)
+#   tag     -- in MUTATIVE_VERBS (creates refs, tag -d deletes)
+
+GIT_LOCAL_SAFE_SUBCOMMANDS: FrozenSet[str] = frozenset({
+    "commit",
+    "stash",
+    "add",
+    "log",
+    "diff",
+    "status",
+    "branch",
+    "checkout",
+    "switch",
+    "reflog",
+    "bisect",
+    "blame",
+    "show",
+    "shortlog",
+    "whatchanged",
+    "notes",
+    "reset",       # local-only: modifies local refs/staging, never touches remote
+    "revert",      # local-only: creates a new commit undoing changes, no remote side effects
+    "cherry-pick", # local-only: applies commits from another branch, no remote side effects
+})
+
+
+# ============================================================================
+# Verb+Flag Overrides (mutative verb downgraded to READ_ONLY by a flag)
+# ============================================================================
+# Map of (cli_family, verb) -> frozenset of flag tokens that override to READ_ONLY.
+# Checked AFTER a mutative verb is found but BEFORE returning the MUTATIVE result.
+
+VERB_FLAG_READ_ONLY_OVERRIDES: Dict[Tuple[str, str], FrozenSet[str]] = {
+    # "git tag -l" / "git tag --list" is listing, not creating/deleting
+    ("git", "tag"): frozenset({"-l", "--list"}),
+}
+
+
+# ============================================================================
+# CLI-Verb Tier Exceptions (unconditional downgrade from MUTATIVE)
+# ============================================================================
+# Downgrade specific (cli_family, verb) combos to a lower tier regardless of
+# flags.  Use only when the API-level semantics of the verb are safe despite
+# the generic verb name being in MUTATIVE_VERBS.
+#
+# Key:   (cli_family, verb)  — cli_family comes from CLI_FAMILY_LOOKUP above.
+# Value: target category constant (CATEGORY_READ_ONLY or CATEGORY_SIMULATION).
+#
+# This dict is protected by the Write/Edit T3 hook (it lives inside the hooks
+# directory).  Modifications require user approval.
+
+CLI_VERB_TIER_EXCEPTIONS: Dict[Tuple[str, str], str] = {
+    # Gmail API: "modify" only changes labels/flags on messages — it cannot
+    # alter message content, send mail, or delete anything.  Safe as T0.
+    ("workspace", "modify"): CATEGORY_READ_ONLY,
+}
+
+
+# ============================================================================
+# Inline Code Detection — Language-Agnostic 3-Layer Approach
+# ============================================================================
+# When the base command is a runtime interpreter with an inline code flag
+# (e.g., python3 -c, node -e, ruby -e, perl -e), scan the code string
+# using three layers instead of verb-matching tokens:
+#   Layer 1: Extract string literals → check against blocked_commands
+#   Layer 2: Universal dangerous API keyword patterns
+#   Layer 3: Heuristic safety classification (length, paths, encoding)
+import re as _re
+
+# ---------------------------------------------------------------------------
+# CLI → inline-code flag mapping (Step 1a)
+# ---------------------------------------------------------------------------
+_INLINE_CODE_MAP: Dict[str, FrozenSet[str]] = {
+    "python": frozenset({"-c"}),
+    "python3": frozenset({"-c"}),
+    "python3.10": frozenset({"-c"}),
+    "python3.11": frozenset({"-c"}),
+    "python3.12": frozenset({"-c"}),
+    "python3.13": frozenset({"-c"}),
+    "node": frozenset({"-e", "--eval"}),
+    "ruby": frozenset({"-e"}),
+    "perl": frozenset({"-e", "-E"}),
+    "php": frozenset({"-r"}),
+    "lua": frozenset({"-e"}),
+    "rscript": frozenset({"-e"}),
+}
+_INLINE_CODE_CLIS: FrozenSet[str] = frozenset(_INLINE_CODE_MAP.keys())
+
+# ---------------------------------------------------------------------------
+# Layer 1: Shell command extraction from string literals
+# ---------------------------------------------------------------------------
+_STRING_LITERAL_RE = _re.compile(r"""(?:['"])((?:[^'"\\\n]|\\.){3,})(?:['"])""")
+
+
+def _extract_embedded_shell_commands(code: str) -> List[str]:
+    """Extract string literals from inline code that may contain shell commands."""
+    return [m.group(1) for m in _STRING_LITERAL_RE.finditer(code)]
+
+
+# ---------------------------------------------------------------------------
+# Layer 2: Universal dangerous API keyword patterns (category-based)
+# ---------------------------------------------------------------------------
+_UNIVERSAL_DANGEROUS_PATTERNS: Tuple[Tuple[_re.Pattern, str, str], ...] = (
+    # Category: Process Execution
+    (_re.compile(r"\b(child_process|subprocess)\b"), "process-module", "PROCESS_EXECUTION"),
+    (_re.compile(r"\b(execSync|execFile|execFileSync)\s*\("), "exec-sync", "PROCESS_EXECUTION"),
+    (_re.compile(r"\bos\.(system|popen|exec[lv]?[pe]?)\s*\("), "os-exec", "PROCESS_EXECUTION"),
+    (_re.compile(r"\b(system|exec)\s*\("), "system-call", "PROCESS_EXECUTION"),
+    (_re.compile(r"\bspawn(Sync)?\s*\("), "spawn-call", "PROCESS_EXECUTION"),
+    (_re.compile(r"\bPopen\s*\("), "popen-call", "PROCESS_EXECUTION"),
+    (_re.compile(r"`[^`]{3,}`"), "backtick-exec", "PROCESS_EXECUTION"),
+
+    # Category: File Deletion
+    (_re.compile(r"\b(os\.remove|os\.unlink|os\.rmdir)\s*\("), "os-delete", "FILE_DELETION"),
+    (_re.compile(r"\b(shutil\.rmtree|shutil\.move)\s*\("), "shutil-delete", "FILE_DELETION"),
+    (_re.compile(r"\bfs\.(unlink|rmdir|rm)(Sync)?\s*\("), "fs-delete", "FILE_DELETION"),
+    # Also match .unlinkSync( / .rmSync( / .rmdirSync( as method calls (e.g., require('fs').unlinkSync())
+    (_re.compile(r"\.(unlink|rmdir|rm)(Sync)?\s*\("), "fs-delete", "FILE_DELETION"),
+    (_re.compile(r"\bFile\.(delete|unlink)\s*\("), "file-delete", "FILE_DELETION"),
+    (_re.compile(r"\bunlink\s*\("), "unlink-call", "FILE_DELETION"),
+    (_re.compile(r"\brmtree\s*\("), "rmtree-call", "FILE_DELETION"),
+    (_re.compile(r"\bFileUtils\.rm"), "fileutils-rm", "FILE_DELETION"),
+    (_re.compile(r"pathlib\.Path\([^)]*\)\.(unlink|rmdir)"), "pathlib-delete", "FILE_DELETION"),
+
+    # Category: File Write
+    (_re.compile(r"open\s*\([^)]*['\"][wWaA]"), "file-write-open", "FILE_WRITE"),
+    (_re.compile(r"\bfs\.writeFile(Sync)?\s*\("), "fs-write", "FILE_WRITE"),
+    # Also match .writeFileSync( / .appendFileSync( as method calls
+    (_re.compile(r"\.writeFile(Sync)?\s*\("), "fs-write", "FILE_WRITE"),
+    (_re.compile(r"\bfs\.appendFile(Sync)?\s*\("), "fs-append", "FILE_WRITE"),
+    (_re.compile(r"\.appendFile(Sync)?\s*\("), "fs-append", "FILE_WRITE"),
+    (_re.compile(r"\bFile\.(write|open)\b.*['\"][wWaA]"), "file-write-ruby", "FILE_WRITE"),
+    (_re.compile(r"\.write\s*\("), "file-write", "FILE_WRITE"),
+    (_re.compile(r"pathlib\.Path\([^)]*\)\.(rename|write_)"), "pathlib-write", "FILE_WRITE"),
+
+    # Category: File System Mutation (os.rename, os.makedirs, shutil.copy)
+    (_re.compile(r"\bos\.rename\s*\("), "os-rename", "FILE_MUTATION"),
+    (_re.compile(r"\bos\.makedirs?\s*\("), "os-makedirs", "FILE_MUTATION"),
+    (_re.compile(r"\bshutil\.copy\s*\("), "shutil-copy", "FILE_MUTATION"),
+
+    # Category: Network
+    (_re.compile(r"\bhttps?://\S+"), "url-literal", "NETWORK"),
+    (_re.compile(r"\b(fetch|axios|requests\.get|urllib)\s*\("), "http-call", "NETWORK"),
+    (_re.compile(r"\bNet::HTTP\b"), "net-http", "NETWORK"),
+
+    # Category: Permission Modification
+    (_re.compile(r"\bos\.chmod\s*\("), "os-chmod", "PERMISSION_MOD"),
+    (_re.compile(r"\bfs\.chmod(Sync)?\s*\("), "fs-chmod", "PERMISSION_MOD"),
+)
+
+# ---------------------------------------------------------------------------
+# Layer 3: Heuristic safety classification
+# ---------------------------------------------------------------------------
+_SUSPICIOUS_HEURISTICS: Tuple[Tuple[_re.Pattern, str], ...] = (
+    (_re.compile(r"\b(base64|b64encode|b64decode|atob|btoa)\b"), "encoding"),
+    (_re.compile(r"\b\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\b"), "ip-address"),
+)
+
+MAX_SAFE_INLINE_LENGTH = 150
+MAX_NORMAL_INLINE_LENGTH = 500
+
+
+# ============================================================================
+# Command Aliases (single-token commands that map to a category)
+# ============================================================================
+
+# All command aliases are MUTATIVE (approvable via nonce).
+# The truly destructive patterns (rm -rf /, dd of=/dev/sda, mkfs, fdisk) are
+# permanently blocked by blocked_commands.py before the verb detector runs.
+COMMAND_ALIASES: Dict[str, str] = {
+    "rm": CATEGORY_MUTATIVE,
+    "rmdir": CATEGORY_MUTATIVE,
+    "mkdir": CATEGORY_MUTATIVE,
+    "mv": CATEGORY_MUTATIVE,
+    "cp": CATEGORY_MUTATIVE,
+    "ln": CATEGORY_MUTATIVE,
+    "dd": CATEGORY_MUTATIVE,
+    "mkfs": CATEGORY_MUTATIVE,
+    "fdisk": CATEGORY_MUTATIVE,
+    "chmod": CATEGORY_MUTATIVE,
+    "chown": CATEGORY_MUTATIVE,
+    "chgrp": CATEGORY_MUTATIVE,
+    "nohup": CATEGORY_MUTATIVE,
+}
+
+
+# ============================================================================
+# Simulation Flags (--dry-run and equivalents)
+# ============================================================================
+
+SIMULATION_FLAGS: FrozenSet[str] = frozenset({
+    "--dry-run",
+    "--dryrun",
+    "--dry-run=client",
+    "--dry-run=server",
+})
+
+
+# ============================================================================
+# --help Exemption Whitelist (T3 -> T0 downgrade for well-known CLIs)
+# ============================================================================
+# Only CLIs listed here get the --help exemption in Step 3.5 of the detection
+# algorithm. Command aliases (rm, mv, dd, etc.) are intentionally excluded:
+# they may process arguments before honoring --help, so keeping them T3
+# preserves safety.
+
+HELP_FLAGS: FrozenSet[str] = frozenset({"--help", "-h", "-?", "--usage"})
+
+# CLI families where `<cli> <verb> --help` is idempotent (exit-and-print).
+# Keys come from CLI_FAMILY_LOOKUP (defined further below in this module).
+HELP_IDEMPOTENT_FAMILIES: FrozenSet[str] = frozenset({
+    "k8s",       # kubectl, helm, flux, kustomize
+    "iac",       # terraform, terragrunt, pulumi
+    "git",       # git subcommands respect --help via man page
+    "docker",    # docker, podman
+    "cloud",     # aws, gcloud, gh, glab, az
+    "package",   # npm, pip, yarn, bun, cargo, brew, apt
+    "build",     # make, cmake, bazel, gradle, mvn
+    "runtime",   # node, python, python3
+    "linter",    # pytest, mypy, ruff, black, flake8
+})
+
+# Explicit base_cmd whitelist (not covered by CLI_FAMILY_LOOKUP).
+HELP_IDEMPOTENT_BASE_CMDS: FrozenSet[str] = frozenset({
+    "gaia",      # project CLI, not in CLI_FAMILY_LOOKUP
+})
+
+# Shell redirect tokens (e.g., "2>&1", ">out", "<in") that shlex produces
+# as non-flag tokens but carry no CLI semantic value. Used by the --help
+# exemption to count only real positional args.
+import re as _re_help
+_SHELL_REDIRECT_RE = _re_help.compile(r"^(\d*[<>]&?\d*|[<>]{1,2}.*)$")
+
+
+# ============================================================================
+# Dangerous Flags (context-sensitive)
+# ============================================================================
+
+DANGEROUS_FLAGS: Dict[str, str] = {
+    "--force": "ALWAYS",
+    "--no-preserve-root": "ALWAYS",
+    "--force-with-lease": "ALWAYS",
+    "--prune": "ALWAYS",
+    "--cascade": "ALWAYS",
+    "--grace-period=0": "ALWAYS",
+    "--now": "ALWAYS",
+    "-f": "CONTEXT",
+    "-r": "CONTEXT",
+    "-R": "CONTEXT",
+    "-D": "CONTEXT",
+    "-M": "CONTEXT",
+    "--recursive": "CONTEXT",
+    "--delete": "CONTEXT",
+    "-rf": "ALWAYS",
+    "-fr": "ALWAYS",
+}
+
+# CLIs where -f means --force (not --file or --format)
+F_FLAG_MEANS_FORCE: FrozenSet[str] = frozenset({
+    "rm", "cp", "mv", "ln", "docker", "podman",
+    "kubectl", "helm", "apt-get", "brew",
+})
+
+# CLIs where -r means recursive delete (not --region or --role)
+R_FLAG_MEANS_RECURSIVE_DELETE: FrozenSet[str] = frozenset({
+    "rm", "cp", "chmod", "chown", "chgrp", "find",
+    "gsutil",
+})
+
+# CLIs where -D means force-delete (not -D for other meanings)
+D_FLAG_MEANS_FORCE_DELETE: FrozenSet[str] = frozenset({
+    "git",
+})
+
+# CLIs where -M means force-move/rename (not -M for other meanings)
+M_FLAG_MEANS_FORCE_MOVE: FrozenSet[str] = frozenset({
+    "git",
+})
+
+# CLIs where --delete is a destructive flag (not a query filter)
+DELETE_FLAG_IS_DESTRUCTIVE: FrozenSet[str] = frozenset({
+    "git", "rsync",
+})
+
+
+# ============================================================================
+# Lightweight CLI Family Lookup (metadata only, not routing)
+# ============================================================================
+
+CLI_FAMILY_LOOKUP: Dict[str, str] = {
+    "kubectl": "k8s", "helm": "k8s", "flux": "k8s", "kustomize": "k8s",
+    "k9s": "k8s", "kubectx": "k8s", "kubens": "k8s", "stern": "k8s",
+    "terraform": "iac", "terragrunt": "iac", "pulumi": "iac", "cdktf": "iac",
+    "git": "git",
+    "docker": "docker", "podman": "docker",
+    "docker-compose": "docker", "podman-compose": "docker",
+    "aws": "cloud", "gcloud": "cloud", "gsutil": "cloud", "az": "cloud",
+    "eksctl": "cloud", "gh": "cloud", "glab": "cloud", "gws": "workspace",
+    "vercel": "cloud", "netlify": "cloud",
+    "fly": "cloud", "flyctl": "cloud", "heroku": "cloud",
+    "npm": "package", "npx": "package", "pnpm": "package",
+    "yarn": "package", "bun": "package", "deno": "package",
+    "pip": "package", "pip3": "package", "poetry": "package",
+    "pipenv": "package", "uv": "package",
+    "apt": "package", "apt-get": "package", "brew": "package",
+    "cargo": "package", "go": "package",
+    "make": "build", "cmake": "build", "bazel": "build",
+    "gradle": "build", "mvn": "build",
+    "node": "runtime", "python": "runtime", "python3": "runtime",
+    "tsx": "runtime", "ts-node": "runtime",
+    "pytest": "linter", "mypy": "linter", "black": "linter",
+    "ruff": "linter", "flake8": "linter", "pylint": "linter",
+    "systemctl": "system", "service": "system", "supervisorctl": "system",
+}
+
+
+# ============================================================================
+# Dangerous Flag Scanning
+# ============================================================================
+
+def _scan_dangerous_flags(
+    tokens: Union[List[str], tuple],
+    cli: str,
+) -> Tuple[str, ...]:
+    """Scan tokens for dangerous flags with context sensitivity.
+
+    Context rules:
+    - "-f" is only dangerous if cli is in F_FLAG_MEANS_FORCE
+    - "-r"/"-R" is only dangerous if cli is in R_FLAG_MEANS_RECURSIVE_DELETE
+    - "-D" is only dangerous if cli is in D_FLAG_MEANS_FORCE_DELETE
+    - "-M" is only dangerous if cli is in M_FLAG_MEANS_FORCE_MOVE
+    - "--delete" is only dangerous if cli is in DELETE_FLAG_IS_DESTRUCTIVE
+    - Compound flags like "-rf" are always dangerous
+
+    Args:
+        tokens: Tokenized command.
+        cli: CLI tool name.
+
+    Returns:
+        Tuple of dangerous flag strings found.
+    """
+    found: List[str] = []
+
+    for token in tokens:
+        if not token.startswith("-"):
+            continue
+
+        # Check exact matches in DANGEROUS_FLAGS
+        if token in DANGEROUS_FLAGS:
+            flag_type = DANGEROUS_FLAGS[token]
+
+            if flag_type == "ALWAYS":
+                found.append(token)
+                continue
+
+            # CONTEXT-sensitive flags
+            if token == "-f":
+                if cli in F_FLAG_MEANS_FORCE:
+                    found.append(token)
+            elif token in ("-r", "-R"):
+                if cli in R_FLAG_MEANS_RECURSIVE_DELETE:
+                    found.append(token)
+            elif token == "-D":
+                if cli in D_FLAG_MEANS_FORCE_DELETE:
+                    found.append(token)
+            elif token == "-M":
+                if cli in M_FLAG_MEANS_FORCE_MOVE:
+                    found.append(token)
+            elif token == "--delete":
+                if cli in DELETE_FLAG_IS_DESTRUCTIVE:
+                    found.append(token)
+            elif token == "--recursive":
+                if cli in R_FLAG_MEANS_RECURSIVE_DELETE:
+                    found.append(token)
+
+        # Check for compound short flags containing dangerous combos
+        # e.g., "-rfi" contains both -r and -f
+        elif len(token) > 2 and token[0] == "-" and token[1] != "-":
+            flag_chars = token[1:]
+            if "r" in flag_chars and "f" in flag_chars:
+                found.append(token)
+            elif "f" in flag_chars and cli in F_FLAG_MEANS_FORCE:
+                found.append(token)
+            elif "r" in flag_chars and cli in R_FLAG_MEANS_RECURSIVE_DELETE:
+                found.append(token)
+
+    return tuple(found)
+
+
+# ============================================================================
+# CamelCase Splitting
+# ============================================================================
+
+def split_camel_case(token: str) -> List[str]:
+    """Split a camelCase token into lowercase component words.
+
+    Examples:
+        "batchDelete"   -> ["batch", "delete"]
+        "deleteMessages" -> ["delete", "messages"]
+        "GET"           -> ["get"]          (all-caps stays as one token)
+        "already_snake" -> ["already_snake"] (no camelCase boundary)
+    """
+    parts = _re.sub(r"([a-z])([A-Z])", r"\1 \2", token).split()
+    return [p.lower() for p in parts] if len(parts) > 1 else [token.lower()]
+
+
+# ============================================================================
+# Main Detection Function
+# ============================================================================
+
+@functools.lru_cache(maxsize=128)
+def detect_mutative_command(command: str) -> MutativeResult:
+    """Analyze a shell command and return a structured mutative assessment.
+
+    Simplified algorithm (CLI-agnostic):
+    1. Tokenize the command.
+    2. COMMAND_ALIASES fast-path.
+    3. Simulation flag override: --dry-run anywhere = not mutative.
+    4. Scan the first semantic non-flag tokens after the base CLI.
+    5. Scan for dangerous flags.
+    6. No match: not mutative (safe by elimination).
+
+    Args:
+        command: Raw shell command string.
+
+    Returns:
+        MutativeResult with full classification details.
+    """
+    # --- Edge case: empty command ---
+    if not command or not command.strip():
+        return MutativeResult(
+            is_mutative=False,
+            category=CATEGORY_UNKNOWN,
+            reason="Empty command",
+            confidence="high",
+        )
+
+    semantics = analyze_command(command)
+    tokens = list(semantics.tokens)
+    if not tokens:
+        return MutativeResult(
+            is_mutative=False,
+            category=CATEGORY_UNKNOWN,
+            reason="No tokens after parsing",
+            confidence="high",
+        )
+
+    base_cmd = semantics.base_cmd
+    family = CLI_FAMILY_LOOKUP.get(base_cmd, "unknown")
+
+    # --- Step 1: Command alias fast-path ---
+    if base_cmd in COMMAND_ALIASES:
+        alias_category = COMMAND_ALIASES[base_cmd]
+        dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+        return MutativeResult(
+            is_mutative=True,
+            category=alias_category,
+            verb=base_cmd,
+            dangerous_flags=dangerous_flags,
+            cli_family=family if family != "unknown" else "system",
+            confidence="high",
+            reason=f"Command alias '{base_cmd}' is {alias_category.lower()}",
+        )
+
+    # --- Step 2: Single-token command (no verb to extract) ---
+    if len(tokens) == 1:
+        return MutativeResult(
+            is_mutative=False,
+            category=CATEGORY_UNKNOWN,
+            verb=base_cmd,
+            cli_family=family,
+            confidence="low",
+            reason=f"Single-token command '{base_cmd}' with no verb",
+        )
+
+    # --- Step 3: Simulation flag override ---
+    if any(t.lower() in SIMULATION_FLAGS for t in tokens):
+        # Find the first non-flag token after base_cmd for the verb
+        verb, _ = _find_first_non_flag(semantics.semantic_head_tokens)
+        return MutativeResult(
+            is_mutative=False,
+            category=CATEGORY_SIMULATION,
+            verb=verb,
+            cli_family=family,
+            confidence="high",
+            reason=f"Simulation flag detected (command has --dry-run or equivalent)",
+        )
+
+    # --- Step 3.5: --help exemption (whitelist + positional boundary) ---
+    # A --help / -h invocation on a well-known CLI only prints usage text.
+    # Three simultaneous conditions are required so the exemption does not
+    # degrade safety on command-aliases or unknown tools:
+    #   (a) CLI is in the whitelist (family OR base_cmd explicitly trusted)
+    #   (b) a help flag is present in the PARSED flags (ignores strings
+    #       that happen to contain "--help" inside a path or argument value)
+    #   (c) the command invocation is simple (<=2 non-flag positional tokens):
+    #       "gaia update --help" (1), "gaia approvals clean --help" (2) OK;
+    #       "kubectl delete pod mypod --help" (3) stays T3 because the CLI
+    #       may process the mutative args before honoring --help.
+    # Root cause: ghost pendings P-738355ab and P-0b06738b were created by
+    # `gaia update --help` and `gaia approvals clean --help` being
+    # classified as MUTATIVE; this exemption prevents recurrence.
+    if (
+        base_cmd in HELP_IDEMPOTENT_BASE_CMDS
+        or family in HELP_IDEMPOTENT_FAMILIES
+    ):
+        flag_set = set(semantics.flag_tokens)
+        # Count semantic non-flag tokens only. Shell redirect shorthands
+        # like "2>&1", ">file", "<file" appear as non-flag tokens in shlex
+        # output but carry no CLI semantic value -- filtering them keeps
+        # "gaia approvals clean --help 2>&1" at threshold 2 instead of 3.
+        semantic_non_flags = [
+            t for t in semantics.non_flag_tokens
+            if not _SHELL_REDIRECT_RE.match(t)
+        ]
+        if flag_set & HELP_FLAGS and len(semantic_non_flags) <= 2:
+            verb = (
+                semantic_non_flags[0]
+                if semantic_non_flags
+                else "help"
+            )
+            return MutativeResult(
+                is_mutative=False,
+                category=CATEGORY_READ_ONLY,
+                verb=verb,
+                cli_family=family,
+                confidence="high",
+                reason=(
+                    f"--help on whitelisted CLI '{base_cmd}' "
+                    f"with simple invocation (<=2 non-flag tokens)"
+                ),
+            )
+
+    # --- Step 3b: Inline code safety check (python3 -c, node -e, etc.) ---
+    # For runtime interpreters with inline code flags, scan the code string
+    # using the 3-layer approach instead of verb-matching tokens (which would
+    # false-positive on generic keywords like "import", "create", etc.).
+    cli_flags = _INLINE_CODE_MAP.get(base_cmd, frozenset())
+    if base_cmd in _INLINE_CODE_CLIS and cli_flags & set(semantics.flag_tokens):
+        return _check_inline_code(command, base_cmd, family)
+
+    # --- Step 3c: Heredoc safety check ---
+    # When a runtime interpreter is invoked with '-' (stdin) and the command
+    # contains a heredoc ('<<'), the heredoc body is script source --
+    # not shell subcommands.  Route through inline code analysis.
+    # The length heuristic is suppressed: multi-line heredocs are normal
+    # and must not be flagged on size alone.
+    if (
+        base_cmd in _INLINE_CODE_CLIS
+        and "<<" in command
+        and semantics.non_flag_tokens
+        and semantics.non_flag_tokens[0] == "-"
+    ):
+        return _check_inline_code(command, base_cmd, family, skip_length_check=True)
+
+    # --- Step 3d: Git local-only subcommand guard ---
+    # When base_cmd is "git" and the subcommand is local-only (commit, stash,
+    # add, log, etc.), short-circuit to non-mutative.  This prevents message
+    # body text after -m from leaking into the verb scanner and triggering
+    # false positives on words like "update", "create", "deploy".
+    # Dangerous flags (-D, -M, --force) are still checked so that
+    # "git branch -D feature" remains flagged.
+    if base_cmd == "git" and semantics.non_flag_tokens:
+        git_subcmd = semantics.non_flag_tokens[0]
+        if git_subcmd in GIT_LOCAL_SAFE_SUBCOMMANDS:
+            dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+            if dangerous_flags:
+                return MutativeResult(
+                    is_mutative=True,
+                    category=CATEGORY_MUTATIVE,
+                    verb=git_subcmd,
+                    dangerous_flags=dangerous_flags,
+                    cli_family=family,
+                    confidence="high",
+                    reason=f"Git local subcommand '{git_subcmd}' with dangerous flags {dangerous_flags}",
+                )
+            return MutativeResult(
+                is_mutative=False,
+                category=CATEGORY_SIMULATION if git_subcmd in SIMULATION_VERBS else CATEGORY_READ_ONLY if git_subcmd in READ_ONLY_VERBS else CATEGORY_UNKNOWN,
+                verb=git_subcmd,
+                cli_family=family,
+                confidence="high",
+                reason=f"Git local-only subcommand '{git_subcmd}' is safe",
+            )
+
+    # --- Step 4: Scan semantic non-flag tokens near the command head ---
+    # Priority order: SIMULATION > MUTATIVE > READ_ONLY > ALIASES
+    for semantic_index, token in enumerate(semantics.semantic_head_tokens[1:], start=1):
+        # Check compound read-only subcommands BEFORE hyphen-split.
+        # Without this, "merge-base" would be split to "merge" -> MUTATIVE.
+        if token in COMPOUND_READ_ONLY_SUBCOMMANDS:
+            return MutativeResult(
+                is_mutative=False,
+                category=CATEGORY_READ_ONLY,
+                verb=token,
+                cli_family=family,
+                confidence="high",
+                reason=f"Compound read-only subcommand '{token}'",
+            )
+
+        # Strip leading '+' macro prefix before verb lookup.
+        # Some CLIs (notably `gws`) expose convenience macros with a '+' prefix
+        # that wrap an underlying mutative API call:
+        #   gws gmail +reply   -> sends a reply (equivalent to messages send)
+        #   gws gmail +send    -> sends a new message
+        #   gws gmail +search  -> list/search wrapper (read-only)
+        # Without stripping '+', these tokens miss MUTATIVE_VERBS / READ_ONLY_VERBS
+        # lookups and fall through to "safe by elimination", bypassing T3 approval.
+        # Stripping here resolves the macro to its base verb so the taxonomy below
+        # classifies it correctly.
+        stripped_token = token.lstrip("+")
+
+        # Split hyphenated tokens: "delete-stack" -> check "delete"
+        candidate = stripped_token.split("-", 1)[0] if "-" in stripped_token else stripped_token
+
+        # Also check full token for exact matches (e.g., "force-delete")
+        full_lower = stripped_token
+
+        # Determine confidence from position
+        confidence = "high" if semantic_index <= 2 else "medium"
+
+        # Check verb taxonomy in priority order
+        if candidate in SIMULATION_VERBS or full_lower in SIMULATION_VERBS:
+            verb = candidate if candidate in SIMULATION_VERBS else full_lower
+            return MutativeResult(
+                is_mutative=False,
+                category=CATEGORY_SIMULATION,
+                verb=verb,
+                cli_family=family,
+                confidence=confidence,
+                reason=f"Simulation verb '{verb}'",
+            )
+
+        if candidate in MUTATIVE_VERBS or full_lower in MUTATIVE_VERBS:
+            verb = candidate if candidate in MUTATIVE_VERBS else full_lower
+
+            # Check verb+flag overrides: some verbs become READ_ONLY with
+            # specific flags (e.g., "git tag -l" is listing, not creating).
+            override_key = (family, verb)
+            if override_key in VERB_FLAG_READ_ONLY_OVERRIDES:
+                override_flags = VERB_FLAG_READ_ONLY_OVERRIDES[override_key]
+                if override_flags & frozenset(semantics.flag_tokens):
+                    return MutativeResult(
+                        is_mutative=False,
+                        category=CATEGORY_READ_ONLY,
+                        verb=verb,
+                        cli_family=family,
+                        confidence="high",
+                        reason=f"Verb '{verb}' overridden to read-only by flag",
+                    )
+
+            # Check unconditional tier exceptions: some (cli_family, verb)
+            # combos are safe despite the verb being in MUTATIVE_VERBS.
+            # Example: Gmail API "modify" only changes labels/flags.
+            exception_key = (family, verb)
+            if exception_key in CLI_VERB_TIER_EXCEPTIONS:
+                target_category = CLI_VERB_TIER_EXCEPTIONS[exception_key]
+                return MutativeResult(
+                    is_mutative=False,
+                    category=target_category,
+                    verb=verb,
+                    cli_family=family,
+                    confidence="high",
+                    reason=f"Verb '{verb}' for '{family}' CLI excepted to {target_category.lower()} by config",
+                )
+
+            dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+            flag_detail = (
+                f" with dangerous flags {dangerous_flags}"
+                if dangerous_flags else ""
+            )
+            return MutativeResult(
+                is_mutative=True,
+                category=CATEGORY_MUTATIVE,
+                verb=verb,
+                dangerous_flags=dangerous_flags,
+                cli_family=family,
+                confidence=confidence,
+                reason=f"Mutative verb '{verb}'{flag_detail}",
+            )
+
+        # --- Secondary check: camelCase splitting ---
+        # "batchDelete" -> ["batch", "delete"] -> "delete" is in MUTATIVE_VERBS
+        # Use the raw (original-case) token because semantic_head_tokens is
+        # lowercased, which destroys the camelCase word boundaries that
+        # split_camel_case relies on (regex: [a-z][A-Z]).
+        raw_token = semantics.semantic_head_tokens_raw[semantic_index] if semantic_index < len(semantics.semantic_head_tokens_raw) else token
+        camel_parts = split_camel_case(raw_token)
+        if len(camel_parts) > 1:
+            for part in camel_parts:
+                if part in MUTATIVE_VERBS:
+                    override_key = (family, part)
+                    if override_key in VERB_FLAG_READ_ONLY_OVERRIDES:
+                        override_flags = VERB_FLAG_READ_ONLY_OVERRIDES[override_key]
+                        if override_flags & frozenset(semantics.flag_tokens):
+                            return MutativeResult(
+                                is_mutative=False,
+                                category=CATEGORY_READ_ONLY,
+                                verb=part,
+                                cli_family=family,
+                                confidence="high",
+                                reason=f"CamelCase verb '{part}' (from '{raw_token}') overridden to read-only by flag",
+                            )
+                    if (family, part) in CLI_VERB_TIER_EXCEPTIONS:
+                        target_category = CLI_VERB_TIER_EXCEPTIONS[(family, part)]
+                        return MutativeResult(
+                            is_mutative=False,
+                            category=target_category,
+                            verb=part,
+                            cli_family=family,
+                            confidence="high",
+                            reason=f"CamelCase verb '{part}' (from '{raw_token}') excepted to {target_category.lower()} by config",
+                        )
+                    dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+                    flag_detail = (
+                        f" with dangerous flags {dangerous_flags}"
+                        if dangerous_flags else ""
+                    )
+                    return MutativeResult(
+                        is_mutative=True,
+                        category=CATEGORY_MUTATIVE,
+                        verb=part,
+                        dangerous_flags=dangerous_flags,
+                        cli_family=family,
+                        confidence=confidence,
+                        reason=f"CamelCase verb '{part}' (from '{raw_token}'){flag_detail}",
+                    )
+
+        if candidate in READ_ONLY_VERBS or full_lower in READ_ONLY_VERBS:
+            verb = candidate if candidate in READ_ONLY_VERBS else full_lower
+            return MutativeResult(
+                is_mutative=False,
+                category=CATEGORY_READ_ONLY,
+                verb=verb,
+                cli_family=family,
+                confidence=confidence,
+                reason=f"Read-only verb '{verb}'",
+            )
+
+        # Check command aliases as verb (e.g., "docker rm" -> rm is alias)
+        if candidate in COMMAND_ALIASES:
+            alias_cat = COMMAND_ALIASES[candidate]
+            dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+            return MutativeResult(
+                is_mutative=True,
+                category=alias_cat,
+                verb=candidate,
+                dangerous_flags=dangerous_flags,
+                cli_family=family,
+                confidence=confidence,
+                reason=f"Verb alias '{candidate}' is {alias_cat.lower()}",
+            )
+
+    # --- Step 4b: API subcommand with no explicit mutative HTTP method ---
+    # CLIs like `gh api` and `glab api` default to GET when no -X flag is
+    # specified.  If the semantic scan found no verb and the subcommand is
+    # "api", treat the command as read-only.
+    if (
+        not any(
+            t in MUTATIVE_VERBS
+            for t in semantics.semantic_head_tokens[1:]
+        )
+        and len(semantics.semantic_head_tokens) > 1
+        and semantics.semantic_head_tokens[1] == "api"
+    ):
+        return MutativeResult(
+            is_mutative=False,
+            category=CATEGORY_READ_ONLY,
+            verb="api",
+            cli_family=family,
+            confidence="high",
+            reason="API call with implicit GET method",
+        )
+
+    # --- Step 5: Scan for dangerous flags (no verb found) ---
+    dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+    if dangerous_flags:
+        # Find first non-flag token as the "verb" for reporting
+        verb, _ = _find_first_non_flag(semantics.semantic_head_tokens)
+        return MutativeResult(
+            is_mutative=True,
+            category=CATEGORY_UNKNOWN,
+            verb=verb,
+            dangerous_flags=dangerous_flags,
+            cli_family=family,
+            confidence="low",
+            reason=f"Unknown verb '{verb}' with dangerous flags {dangerous_flags}",
+        )
+
+    # --- Step 6: No match -- not mutative (safe by elimination) ---
+    verb, _ = _find_first_non_flag(semantics.semantic_head_tokens)
+    return MutativeResult(
+        is_mutative=False,
+        category=CATEGORY_UNKNOWN,
+        verb=verb,
+        cli_family=family,
+        confidence="low",
+        reason=f"Unknown verb '{verb}' with no dangerous flags",
+    )
+
+
+# ============================================================================
+# Helpers
+# ============================================================================
+
+def _check_inline_code(command: str, base_cmd: str, family: str, skip_length_check: bool = False) -> MutativeResult:
+    """Check inline code for dangerous patterns using a 3-layer approach.
+
+    Layer 1: Extract string literals from inline code and check them against
+             blocked_commands (catches embedded shell commands like 'rm -rf /').
+    Layer 2: Scan for universal dangerous API keywords (language-agnostic).
+    Layer 3: Heuristic safety classification (length, sensitive paths, encoding).
+
+    Args:
+        command: Full raw command string.
+        base_cmd: The interpreter (e.g., "python3", "node", "ruby").
+        family: CLI family hint.
+
+    Returns:
+        MutativeResult -- MUTATIVE if any layer triggers, else safe.
+    """
+    # ---- Layer 1: Extract string literals → check against blocked_commands ----
+    if _is_blocked_command is not None:
+        embedded_strings = _extract_embedded_shell_commands(command)
+        for literal in embedded_strings:
+            blocked = _is_blocked_command(literal)
+            if blocked.is_blocked:
+                return MutativeResult(
+                    is_mutative=True,
+                    category=CATEGORY_MUTATIVE,
+                    verb="embedded-blocked-cmd",
+                    cli_family=family,
+                    confidence="high",
+                    reason=(
+                        f"Inline code contains blocked shell command in "
+                        f"string literal: {blocked.category}"
+                    ),
+                )
+
+    # ---- Layer 2: Universal dangerous API keyword patterns ----
+    for pattern, label, category in _UNIVERSAL_DANGEROUS_PATTERNS:
+        if pattern.search(command):
+            return MutativeResult(
+                is_mutative=True,
+                category=CATEGORY_MUTATIVE,
+                verb=label,
+                cli_family=family,
+                confidence="medium",
+                reason=f"Inline code contains dangerous pattern: {label} ({category})",
+            )
+
+    # ---- Layer 3: Heuristic safety classification ----
+    # 3a: Check for suspicious indicators (sensitive paths, encoding, IPs)
+    for pattern, label in _SUSPICIOUS_HEURISTICS:
+        if pattern.search(command):
+            return MutativeResult(
+                is_mutative=True,
+                category=CATEGORY_MUTATIVE,
+                verb=f"heuristic-{label}",
+                cli_family=family,
+                confidence="low",
+                reason=f"Inline code flagged by heuristic: {label}",
+            )
+
+    # 3b: Unusually long inline code is suspicious
+    # Extract the code portion after the inline flag for length check.
+    # Use a rough extraction: everything after the first inline flag.
+    code_portion = command
+    cli_flag_tokens = _INLINE_CODE_MAP.get(base_cmd, frozenset())
+    for flag in cli_flag_tokens:
+        idx = command.find(f" {flag} ")
+        if idx != -1:
+            code_portion = command[idx + len(flag) + 2:]
+            break
+
+    if not skip_length_check and len(code_portion) > MAX_NORMAL_INLINE_LENGTH:
+        return MutativeResult(
+            is_mutative=True,
+            category=CATEGORY_MUTATIVE,
+            verb="heuristic-long-code",
+            cli_family=family,
+            confidence="low",
+            reason=(
+                f"Inline code is unusually long ({len(code_portion)} chars > "
+                f"{MAX_NORMAL_INLINE_LENGTH} limit)"
+            ),
+        )
+
+    # ---- No layers triggered -- safe inline code ----
+    return MutativeResult(
+        is_mutative=False,
+        category=CATEGORY_READ_ONLY,
+        verb="inline-code",
+        cli_family=family,
+        confidence="medium",
+        reason=f"Inline code ({base_cmd}) with no dangerous patterns",
+    )
+
+
+def _find_first_non_flag(tokens: Union[List[str], tuple]) -> tuple:
+    """Find the first semantic token after tokens[0].
+
+    Returns:
+        (verb, position) tuple. ("", -1) if no non-flag token found.
+    """
+    for i in range(1, len(tokens)):
+        if tokens[i]:
+            return tokens[i], i
+    return "", -1
+
+
+# ============================================================================
+# Hook Response Builder
+# ============================================================================
+
+def build_t3_block_response(
+    command: str,
+    danger: MutativeResult,
+    nonce: str = "",
+) -> dict:
+    """Build an internal block response dict for T3 commands.
+
+    Returns an internal dict consumed by bash_validator, which wraps the
+    'message' field into a hookSpecificOutput with permissionDecision: "deny".
+    The 'decision' key is internal only and never sent to Claude Code.
+
+    Args:
+        command: The original shell command.
+        danger: MutativeResult from detect_mutative_command.
+        nonce: Cryptographic nonce for this pending approval. When provided,
+            the block message includes the approval code that the agent must
+            present to the user.
+
+    Returns:
+        Dict with 'decision' (internal) and 'message' (forwarded to agent) keys.
+    """
+    flag_warning = ""
+    if danger.dangerous_flags:
+        flag_warning = (
+            f"\nDangerous flags detected: {', '.join(danger.dangerous_flags)}"
+        )
+
+    message = (
+        f"[T3_APPROVAL_REQUIRED] {danger.category} operation detected.\n"
+        f"Command: {command}\n"
+        f"Verb: '{danger.verb}' (CLI family: {danger.cli_family})\n"
+        f"Confidence: {danger.confidence}\n"
+        f"Reason: {danger.reason}{flag_warning}\n"
+        f"\n"
+        f"{build_t3_approval_instructions(nonce)}"
+    )
+
+    return {
+        "decision": "block",
+        "message": message,
+    }
+
+