@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-ops/hooks/modules/tools/bash_validator.py

@@ -0,0 +1,1008 @@
+"""
+Bash command validator.
+
+Primary security gate for all Bash tool invocations. With Bash(*) in the
+settings.json allow list, ALL commands reach this hook -- it is the sole
+enforcement layer for dangerous command detection.
+
+5-Phase Pipeline:
+  1. UNWRAP      -- ShellUnwrapper strips wrapper shells (bash -c, sh -c, ...);
+                    depth >= _OBFUSCATION_DEPTH_LIMIT = permanent block.
+                    Existing _detect_indirect_execution() runs as fallback for
+                    eval, python -c, node -e, etc.
+  2. DECOMPOSE   -- StageDecomposer splits into operator-linked stages.
+  3. CLASSIFY    -- blocked_commands + cloud_pipe_validator + mutative_verbs
+                    per stage (existing logic, unchanged).
+  4. COMPOSITION -- cross-stage composition rules (exfiltration, RCE,
+                    obfuscated exec via pipe analysis).
+  5. AGGREGATE   -- combine stage results into final BashValidationResult.
+
+Earlier flat-pipeline order preserved within phases for backward compat:
+  - Footer stripping runs before phase 1 (EARLY NORMALIZATION)
+  - Indirect execution detection is the first check in phase 1
+  - Blocked commands run before cloud_pipe and mutative_verbs in phase 3
+"""
+
+import os
+import re
+import json
+import logging
+from typing import Dict, Any, Optional, List
+from dataclasses import dataclass
+
+from ..security.tiers import SecurityTier
+from ..security.blocked_commands import is_blocked_command
+from ..security.gitops_validator import validate_gitops_workflow
+from ..security.mutative_verbs import (
+    detect_mutative_command,
+    build_t3_block_response,
+)
+from ..security.flag_classifiers import (
+    classify_by_flags,
+    OUTCOME_BLOCKED as FLAG_BLOCKED,
+    OUTCOME_MUTATIVE as FLAG_MUTATIVE,
+)
+from ..security.approval_grants import (
+    check_approval_grant,
+    confirm_grant,
+    find_pending_for_command,
+    generate_nonce,
+    last_check_found_expired,
+    write_pending_approval,
+)
+from ..security.approval_messages import (
+    build_pending_approval_unavailable_message,
+    build_t3_approval_instructions,
+)
+from ..security.shell_unwrapper import ShellUnwrapper
+from ..security.composition_rules import (
+    build_composition_stages,
+    check_composition,
+    CompositionDecision,
+)
+from .shell_parser import get_shell_parser
+from .cloud_pipe_validator import validate_cloud_pipe
+from .hook_response import build_hook_permission_response
+from .stage_decomposer import StageDecomposer, DecomposedCommand
+
+logger = logging.getLogger(__name__)
+
+# Maximum wrapper depth before treating as obfuscation (permanent block).
+_OBFUSCATION_DEPTH_LIMIT = 5
+
+
+@dataclass
+class BashValidationResult:
+    """Result of Bash command validation."""
+    allowed: bool
+    tier: SecurityTier
+    reason: str
+    suggestions: List[str] = None
+    modified_input: Optional[Dict[str, Any]] = None
+    # When set, the caller should return this dict (exit 0) instead of a
+    # plain error string (exit 2).  Used for structured block responses that
+    # should correct the agent rather than terminate execution.
+    block_response: Optional[Dict[str, Any]] = None
+
+    def __post_init__(self):
+        if self.suggestions is None:
+            self.suggestions = []
+
+
+# Patterns for AI tool attribution footers (auto-stripped from commits).
+# Covers Claude Code, GitHub Copilot, Aider, Windsurf, and any future
+# tool using the Co-authored-by git trailer convention.
+FORBIDDEN_FOOTER_PATTERNS = [
+    r"Generated with\s+Claude Code",
+    r"Generated with\s+\[?Claude Code\]?",
+    r"Co-Authored-By:\s+Claude\b",
+    r"Co-authored-by:\s+GitHub Copilot\b",
+    r"Co-authored-by:\s+aider\b",
+    r"Co-authored-by:\s+Windsurf\b",
+    r"Co-authored-by:\s+Cursor\b",
+    r"Co-authored-by:\s+Codex\b",
+    r"Co-authored-by:\s+Gemini\b",
+]
+
+# ---------------------------------------------------------------------------
+# Indirect execution wrappers — commands that execute arbitrary strings.
+# These bypass regex-based command blocking because the real command is
+# hidden inside a string argument.  Classified as T2 (requires approval)
+# so the user sees what will actually run.
+# ---------------------------------------------------------------------------
+# Optional prefix commands that can wrap any shell invocation.
+# nohup, sudo, env, nice, etc. — the regex allows zero or more of these
+# before the real interpreter token so "nohup bash -c ..." is still caught.
+_WRAPPER_PREFIX = r"(?:(?:nohup|sudo|env|nice|ionice|setsid|strace|ltrace|time)\s+)*"
+
+INDIRECT_EXEC_PATTERNS = [
+    re.compile(r"^" + _WRAPPER_PREFIX + r"bash\s+-c\s+", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"sh\s+-c\s+", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"zsh\s+-c\s+", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"dash\s+-c\s+", re.IGNORECASE),
+    re.compile(r"^\s*eval\s+", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"python3?\s+-c\s+", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"node\s+-e\s+", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"perl\s+-e\s+", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"ruby\s+-e\s+", re.IGNORECASE),
+    # Process substitution and heredoc piped to shell
+    re.compile(r"^" + _WRAPPER_PREFIX + r"bash\s+<\(", re.IGNORECASE),
+    re.compile(r"^" + _WRAPPER_PREFIX + r"sh\s+<\(", re.IGNORECASE),
+]
+
+class BashValidator:
+    """Validator for Bash tool invocations.
+
+    Implements a 5-phase pipeline: unwrap -> decompose -> classify ->
+    composition -> aggregate.  See module docstring for phase details.
+    """
+
+    def __init__(self):
+        """Initialize validator with parser, unwrapper, and decomposer."""
+        self.shell_parser = get_shell_parser()
+        self._unwrapper = ShellUnwrapper()
+        self._decomposer = StageDecomposer()
+
+    def _detect_indirect_execution(self, command: str) -> Optional[BashValidationResult]:
+        """Detect indirect execution wrappers that can bypass regex blocking.
+
+        Commands like 'bash -c "az group delete"' hide the real command inside
+        a string.  We classify these as T2 (mutative) so they require user
+        approval via the nonce workflow, giving the human a chance to inspect
+        what will actually run.
+
+        Returns BashValidationResult if indirect execution detected, else None.
+        """
+        for pattern in INDIRECT_EXEC_PATTERNS:
+            if pattern.search(command):
+                # Also check if the inner payload contains a blocked command.
+                # Extract the string argument after the wrapper.
+                inner = self._extract_inner_command(command)
+                if inner:
+                    blocked = is_blocked_command(inner)
+                    if blocked.is_blocked:
+                        return BashValidationResult(
+                            allowed=False,
+                            tier=SecurityTier.T3_BLOCKED,
+                            reason=(
+                                f"Indirect execution of blocked command detected: "
+                                f"{blocked.category} (via wrapper)"
+                            ),
+                            suggestions=[
+                                blocked.suggestion or "Run the command directly instead of via a shell wrapper.",
+                            ],
+                        )
+
+                # Not blocked but still indirect — route through approval
+                logger.info("Indirect execution detected: %s", command[:80])
+                result = detect_mutative_command(command)
+                if result.is_mutative:
+                    return None  # Already mutative, will be caught by mutative_verbs
+
+                # For interpreters with inline code analysis (python3 -c),
+                # mutative_verbs.py has dedicated pattern scanning that
+                # distinguishes safe code (json.dumps, sys.version) from
+                # dangerous code (os.system, subprocess.run). If it classified
+                # the inline code as safe, trust that analysis and allow it
+                # through without forcing an "ask" dialog.
+                from ..security.mutative_verbs import _INLINE_CODE_CLIS
+                base_cmd = command.strip().split()[0].rsplit("/", 1)[-1].lower()
+                if base_cmd in _INLINE_CODE_CLIS:
+                    logger.info(
+                        "Inline code classified as safe by pattern scanner: %s",
+                        command[:80],
+                    )
+                    return None  # Safe inline code, proceed to normal validation
+
+                # Shell wrappers (bash -c, eval, etc.) hide the real command
+                # in a string — no dedicated scanner exists. Force "ask" so
+                # the user can inspect what will actually run.
+                #
+                # Inspect the inner command to identify the mutative verb so
+                # the user sees a more informative message
+                # (e.g. "inner mutative verb 'mv'"). Falls back to generic
+                # message when inner has no mutative verb.
+                reason_msg = "Indirect execution wrapper detected — requires confirmation"
+                if inner:
+                    inner_result = detect_mutative_command(inner)
+                    if inner_result.is_mutative and inner_result.verb:
+                        reason_msg = (
+                            f"Indirect execution detected: inner mutative verb "
+                            f"'{inner_result.verb}' — requires confirmation"
+                        )
+                dialog_msg = (
+                    "Indirect execution detected. The command uses a shell "
+                    "wrapper (bash -c, eval, etc.) that can bypass "
+                    "security checks. Please confirm you want to run this."
+                )
+                hook_block = build_hook_permission_response("ask", dialog_msg)
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T2_DRY_RUN,
+                    reason=reason_msg,
+                    block_response=hook_block,
+                )
+        return None
+
+    def _extract_inner_command(self, command: str) -> Optional[str]:
+        """Extract the inner command from an indirect execution wrapper.
+
+        E.g., 'bash -c "az group delete --name foo"' → 'az group delete --name foo'
+        """
+        # Match: shell -c "..." or shell -c '...'
+        match = re.search(r"""-[ce]\s+(['"])(.*?)\1""", command, re.DOTALL)
+        if match:
+            return match.group(2).strip()
+        # Match: shell -c ... (unquoted, take rest of line)
+        match = re.search(r"-[ce]\s+(\S+.*)", command)
+        if match:
+            return match.group(1).strip()
+        return None
+
+    def _has_operators(self, command: str) -> bool:
+        """Quick check if command has operators (before parsing).
+
+        Detects pipes, logical operators, semicolons, redirects, and
+        background operators.  This is a fast pre-filter — the full
+        shell parser handles quote-aware splitting downstream.
+
+        Note: '>' and '&' are included so commands with redirects or
+        background operators reach the compound path, where the
+        sanitization layer can strip them.
+        """
+        # Fast check for common operators outside quotes
+        # This avoids expensive parsing for 70% of commands
+        if not any(op in command for op in ['|', '&&', '||', ';', '\n', '>', '&']):
+            return False
+        return True
+
+    # Regex patterns for operators that can be safely stripped from commands.
+    # Applied after quote-masking to avoid false positives.
+    _NOHUP_PREFIX_RE = re.compile(r"^\s*nohup\s+")
+    _TRAILING_BG_RE = re.compile(r"\s*&\s*$")
+    _REDIRECT_RE = re.compile(r"\s*>{1,2}\s*\S+\s*$")
+    # Fd duplication (2>&1) is harmless and should NOT be stripped.
+    _FD_DUP_RE = re.compile(r"\d+>&\d+")
+
+    def _try_sanitize_command(self, command: str) -> Optional[BashValidationResult]:
+        """Attempt to strip dangerous operators and return a clean command.
+
+        Sanitizable patterns (can be stripped without changing semantics):
+        - nohup prefix:  ``nohup cmd args`` -> ``cmd args``
+        - trailing &:    ``cmd args &``      -> ``cmd args``
+        - trailing redirect: ``cmd args > file`` -> ``cmd args``
+
+        Non-sanitizable patterns (reject with guidance):
+        - Pipes (change data flow between commands)
+        - Chaining operators (&&, ||, ;) — use one-command-per-step
+
+        Returns:
+            BashValidationResult with cleaned command via modified_input if
+            sanitization succeeded, or a block response if it cannot be cleaned.
+            None if no sanitization is needed (command has no dangerous operators).
+        """
+        original = command
+        cleaned = command
+        stripped_parts = []
+
+        # Strip nohup prefix
+        if self._NOHUP_PREFIX_RE.match(cleaned):
+            cleaned = self._NOHUP_PREFIX_RE.sub("", cleaned).strip()
+            stripped_parts.append("nohup")
+
+        # Strip trailing & (background) but not && or >&
+        # Mask fd duplications first to avoid false matching
+        test_str = self._FD_DUP_RE.sub("", cleaned)
+        if self._TRAILING_BG_RE.search(test_str):
+            cleaned = self._TRAILING_BG_RE.sub("", cleaned).strip()
+            stripped_parts.append("&")
+
+        # Strip trailing redirect (> file or >> file)
+        # Only strip if it's at the end of the command
+        test_str = self._FD_DUP_RE.sub("", cleaned)
+        redirect_match = self._REDIRECT_RE.search(test_str)
+        if redirect_match:
+            # Find the position in the original cleaned string
+            # We need to remove from the redirect operator onward
+            pos = cleaned.rfind(">")
+            if pos > 0:
+                before_redirect = cleaned[:pos].rstrip()
+                # Only strip if the > is not inside a flag value like --output=>
+                if before_redirect and not before_redirect.endswith("="):
+                    cleaned = before_redirect
+                    stripped_parts.append("> redirect")
+
+        if not stripped_parts:
+            return None  # Nothing to sanitize
+
+        if cleaned == original:
+            return None  # Sanitization didn't change anything
+
+        logger.info(
+            "Command sanitized: stripped [%s] from: %s",
+            ", ".join(stripped_parts),
+            original[:80],
+        )
+
+        # Build the response with the cleaned command via updatedInput
+        reason = (
+            f"Command sanitized: stripped {', '.join(stripped_parts)}. "
+            f"Read the command-execution skill for proper patterns.\n"
+            f"Original: {original[:120]}\n"
+            f"Cleaned:  {cleaned[:120]}"
+        )
+        hook_response = build_hook_permission_response(
+            "allow", reason, updated_input={"command": cleaned}
+        )
+        # Inject updatedInput into the response for the hook entry point
+        hook_response.setdefault("hookSpecificOutput", {})["updatedInput"] = {
+            "command": cleaned
+        }
+        return BashValidationResult(
+            allowed=True,
+            tier=SecurityTier.T0_READ_ONLY,
+            reason=reason,
+            modified_input={"command": cleaned},
+            block_response=hook_response,
+        )
+
+    def validate(
+        self,
+        command: str,
+        is_subagent: bool = False,
+        session_id: str = "",
+    ) -> BashValidationResult:
+        """
+        Validate a Bash command through the 5-phase pipeline.
+
+        Phases:
+            1. UNWRAP      - strip shell wrappers, detect obfuscation
+            2. DECOMPOSE   - split into operator-linked stages
+            3. CLASSIFY    - blocked_commands + cloud_pipe + mutative_verbs
+            4. COMPOSITION - cross-stage pattern checks (stub for T4)
+            5. AGGREGATE   - combine results into final verdict
+
+        Args:
+            command: Command string to validate
+            is_subagent: True when running in subagent context
+            session_id: Session ID for approval scoping
+
+        Returns:
+            BashValidationResult with validation details
+        """
+        if not command or not command.strip():
+            return BashValidationResult(
+                allowed=False,
+                tier=SecurityTier.T3_BLOCKED,
+                reason="Empty command not allowed",
+            )
+
+        command = command.strip()
+
+        # ================================================================
+        # EARLY NORMALIZATION: Strip AI attribution footers before any
+        # other processing.  This ensures the same normalized command
+        # string is used for blocked-command checks, compound parsing,
+        # mutative verb detection, pending approval writes, AND pending
+        # approval lookups.  Without this, write_pending_approval() and
+        # find_pending_for_command() could see different strings on the
+        # first attempt vs. retry, causing nonce mismatch loops.
+        # ================================================================
+        command_was_modified = False
+        if self._detect_claude_footers(command):
+            command = self._strip_claude_footers(command)
+            command_was_modified = True
+            logger.info("Auto-stripped Claude Code footer from commit command")
+
+        # ================================================================
+        # PHASE 1: UNWRAP
+        # Use ShellUnwrapper to detect and strip shell wrapper layers
+        # (bash -c, sh -c, env bash -c, etc.).  If the wrapper nesting
+        # depth exceeds _OBFUSCATION_DEPTH_LIMIT, permanently block
+        # the command as obfuscated.
+        #
+        # After the unwrapper, _detect_indirect_execution() runs as a
+        # fallback for patterns the unwrapper does not cover: eval,
+        # python -c, node -e, perl -e, ruby -e, process substitution.
+        # ================================================================
+        unwrap_result = self._unwrapper.unwrap(command)
+        if unwrap_result.depth >= _OBFUSCATION_DEPTH_LIMIT:
+            return BashValidationResult(
+                allowed=False,
+                tier=SecurityTier.T3_BLOCKED,
+                reason=(
+                    f"Obfuscated shell nesting detected: {unwrap_result.depth} "
+                    f"wrapper layers exceeds limit of {_OBFUSCATION_DEPTH_LIMIT}"
+                ),
+            )
+
+        indirect_result = self._detect_indirect_execution(command)
+        if indirect_result is not None:
+            return indirect_result
+
+        # ================================================================
+        # PHASE 2: DECOMPOSE
+        # Split the command into operator-linked stages using
+        # StageDecomposer.  The decomposed result is available for
+        # phase 4 (composition rules, T4) and provides operator context
+        # that ShellCommandParser.parse() discards.
+        # ================================================================
+        decomposed = self._decomposer.decompose(command)
+
+        # ================================================================
+        # PHASE 3: CLASSIFY STAGES
+        # Apply existing classification logic in priority order:
+        #   3a. blocked_commands on full command (exit 2)
+        #   3b. blocked_commands on each compound component (exit 2)
+        #   3c. Git commit message validation
+        #   3d. Smart sanitization (strip nohup, &, redirects)
+        #   3e. Cloud pipe/redirect/chain check (corrective deny)
+        #   3f. Dispatch to single/compound classification
+        #        (mutative_verbs, gitops_validator, safe-by-elimination)
+        # ================================================================
+
+        # 3a. Blocked commands check on FULL command (exit 2).
+        # This MUST run before any other classifier to ensure permanently
+        # blocked commands (kubectl delete namespace, etc.) are caught
+        # with a reliable exit 2.
+        blocked_result = is_blocked_command(command)
+        if blocked_result.is_blocked:
+            return BashValidationResult(
+                allowed=False,
+                tier=SecurityTier.T3_BLOCKED,
+                reason=f"Command blocked by security policy: {blocked_result.category}",
+                suggestions=[blocked_result.suggestion] if blocked_result.suggestion else [],
+            )
+
+        # 3b. Parse compound commands and check each component against the
+        # deny list.  Uses ShellCommandParser (not StageDecomposer) for
+        # backward compat — the decomposed stages are used in phase 4.
+        has_operators = self._has_operators(command)
+        parsed_components = None
+        if has_operators:
+            parsed_components = self.shell_parser.parse(command)
+            # Check each component against the deny list.
+            # This catches "ls && kubectl delete namespace prod" early.
+            for component in parsed_components:
+                comp_blocked = is_blocked_command(component.strip())
+                if comp_blocked.is_blocked:
+                    return BashValidationResult(
+                        allowed=False,
+                        tier=SecurityTier.T3_BLOCKED,
+                        reason=f"Command blocked by security policy: {comp_blocked.category}",
+                        suggestions=[comp_blocked.suggestion] if comp_blocked.suggestion else [],
+                    )
+
+        # 3c. Validate git commit messages (on the potentially cleaned command).
+        if "git commit" in command and "-m" in command:
+            commit_validation = self._validate_commit_message(command)
+            if not commit_validation.allowed:
+                return commit_validation
+
+        # 3d. Smart sanitization: strip nohup, trailing &, trailing redirect.
+        sanitized = self._try_sanitize_command(command)
+        if sanitized is not None:
+            if sanitized.allowed:
+                return sanitized
+            else:
+                return sanitized
+
+        # 3e. Cloud pipe/redirect/chaining check.
+        pipe_block = validate_cloud_pipe(command)
+        if pipe_block is not None:
+            return BashValidationResult(
+                allowed=False,
+                tier=SecurityTier.T3_BLOCKED,
+                reason=pipe_block["hookSpecificOutput"]["permissionDecisionReason"],
+                suggestions=[],
+                modified_input=None,
+                block_response=pipe_block,
+            )
+
+        # ================================================================
+        # PHASE 4: CHECK COMPOSITION
+        # Cross-stage composition rules detect dangerous pipe patterns:
+        #   - Exfiltration: sensitive_read | network_write
+        #   - RCE:          network_read   | exec_sink
+        #   - Obfuscated:   decode         | exec_sink
+        #   - File-to-exec: file_read      | exec_sink  (escalate)
+        # Only pipe-connected stages are checked; &&/; are independent.
+        # ================================================================
+        _composition_result = self._phase4_check_composition(decomposed)
+        if _composition_result is not None:
+            return _composition_result
+
+        # ================================================================
+        # PHASE 5: AGGREGATE
+        # 3f. Dispatch to per-stage classifiers (single or compound)
+        # and combine into the final BashValidationResult.
+        # ================================================================
+        if not has_operators:
+            result = self._validate_single_command(
+                command, is_subagent=is_subagent, session_id=session_id,
+            )
+        elif parsed_components is not None and len(parsed_components) > 1:
+            result = self._validate_compound_command(
+                parsed_components, is_subagent=is_subagent, session_id=session_id,
+            )
+        else:
+            result = self._validate_single_command(
+                command, is_subagent=is_subagent, session_id=session_id,
+            )
+
+        # Attach cleaned command for hook to emit via updatedInput.
+        # Set regardless of result.allowed so the ask path can include it too.
+        if command_was_modified:
+            result.modified_input = {"command": command}
+            # If the result is an "ask" block_response, inject updatedInput
+            # so the modification survives the native permission dialog.
+            if (
+                result.block_response is not None
+                and result.block_response.get("hookSpecificOutput", {}).get(
+                    "permissionDecision"
+                ) == "ask"
+            ):
+                result.block_response["hookSpecificOutput"]["updatedInput"] = {
+                    "command": command
+                }
+
+        return result
+
+    def _validate_single_command(
+        self,
+        command: str,
+        is_subagent: bool = False,
+        session_id: str = "",
+    ) -> BashValidationResult:
+        """Validate a single command (no operators).
+
+        Simplified pipeline:
+        0. Indirect execution detection (for compound command components)
+        1. Mutative verb detection -> block with nonce or allow with grant
+        2. GitOps policy validation (for kubectl/helm/flux)
+        3. Everything else -> SAFE by elimination
+
+        Args:
+            command: The command to validate.
+            is_subagent: True when running in subagent context (generates
+                approval_id + deny). False for orchestrator (returns ask).
+            session_id: Session ID for pending approval scoping.
+
+        Note: is_blocked_command() is NOT called here because validate()
+        already checks the full command AND each compound component against
+        the deny list before dispatching to this method.
+        """
+
+        # Indirect execution check for compound command components.
+        # When validate() splits "cd /tmp && python3 -c '...'" into parts,
+        # the python3 -c component needs the same indirect execution gate
+        # that the full command gets in validate().
+        indirect_result = self._detect_indirect_execution(command)
+        if indirect_result is not None:
+            return indirect_result
+
+        # Mutative verb detection
+        result = detect_mutative_command(command)
+        if result.is_mutative:
+            # Check for an active approval grant before blocking.
+            grant = check_approval_grant(command, session_id=session_id)
+            if grant is not None:
+                if grant.confirmed:
+                    # Already confirmed and consumed -- should not reach
+                    # here (single-use). But if it does, allow through.
+                    logger.info(
+                        "T3 command allowed via confirmed grant: %s (scope='%s')",
+                        command[:80], grant.approved_scope,
+                    )
+                    return BashValidationResult(
+                        allowed=True,
+                        tier=SecurityTier.T3_BLOCKED,
+                        reason="Grant confirmed",
+                    )
+                else:
+                    # Grant exists, not yet confirmed -- GAIA approved,
+                    # let it through. PostToolUse will confirm and consume
+                    # the grant after successful execution.
+                    logger.info(
+                        "T3 command passthrough via active grant: %s (scope='%s')",
+                        command[:80], grant.approved_scope,
+                    )
+                    return BashValidationResult(
+                        allowed=True,
+                        tier=SecurityTier.T3_BLOCKED,
+                        reason="Grant active, pending confirmation",
+                    )
+            else:
+                if is_subagent:
+                    # Subagent context: check for an existing pending
+                    # approval first (retry scenario). If found, reuse
+                    # the same nonce to prevent infinite approval_id
+                    # generation loops while the user reviews.
+                    existing_nonce = find_pending_for_command(
+                        session_id or "", command,
+                    )
+                    if existing_nonce:
+                        approval_id = existing_nonce
+                        logger.info(
+                            "Reusing pending approval_id=%s for retry: %s",
+                            approval_id, command[:80],
+                        )
+                        reason = (
+                            f"[T3_BLOCKED] This command requires user approval.\n"
+                            f"Do NOT retry this command. Report APPROVAL_REQUEST with this approval_id in your json:contract.\n"
+                            f"Command: {command}\n"
+                            f"Verb: '{result.verb}' ({result.category})\n"
+                            f"approval_id: {approval_id}"
+                        )
+                        hook_deny = build_hook_permission_response("deny", reason)
+                        return BashValidationResult(
+                            allowed=False,
+                            tier=SecurityTier.T3_BLOCKED,
+                            reason=f"T3 {result.category.lower()} command: {result.reason}",
+                            block_response=hook_deny,
+                        )
+                    # No existing pending -- generate a new nonce.
+                    # The ElicitationResult hook will activate the
+                    # grant when the user approves via AskUserQuestion.
+                    approval_id = generate_nonce()
+                    pending_path = write_pending_approval(
+                        nonce=approval_id,
+                        command=command,
+                        danger_verb=result.verb,
+                        danger_category=result.category,
+                        session_id=session_id or None,
+                        cwd=os.getcwd(),
+                    )
+                    if pending_path is None:
+                        # Persistence failure — fall back to ask
+                        logger.warning(
+                            "Failed to persist pending approval for subagent; "
+                            "falling back to ask: %s",
+                            command[:80],
+                        )
+                        reason = build_pending_approval_unavailable_message()
+                        hook_ask = build_hook_permission_response("ask", reason)
+                        return BashValidationResult(
+                            allowed=False,
+                            tier=SecurityTier.T3_BLOCKED,
+                            reason="Pending approval persistence failed",
+                            block_response=hook_ask,
+                        )
+                    reason = (
+                        f"[T3_BLOCKED] This command requires user approval.\n"
+                        f"Do NOT retry this command. Report APPROVAL_REQUEST with this approval_id in your json:contract.\n"
+                        f"Command: {command}\n"
+                        f"Verb: '{result.verb}' ({result.category})\n"
+                        f"approval_id: {approval_id}"
+                    )
+                    hook_deny = build_hook_permission_response("deny", reason)
+                    return BashValidationResult(
+                        allowed=False,
+                        tier=SecurityTier.T3_BLOCKED,
+                        reason=f"T3 {result.category.lower()} command: {result.reason}",
+                        block_response=hook_deny,
+                    )
+                else:
+                    # Orchestrator context: route through native 'ask' dialog.
+                    # The user sees the native permission prompt and approves
+                    # directly. No approval_id is generated.
+                    reason = (
+                        f"[T3_APPROVAL_REQUIRED] {result.category} operation detected.\n"
+                        f"Command: {command}\n"
+                        f"Verb: '{result.verb}' ({result.category})\n"
+                        f"Reason: {result.reason}"
+                    )
+                    hook_ask = build_hook_permission_response("ask", reason)
+                    return BashValidationResult(
+                        allowed=False,
+                        tier=SecurityTier.T3_BLOCKED,
+                        reason=f"Dangerous {result.category.lower()} command: {result.reason}",
+                        block_response=hook_ask,
+                    )
+
+        # Check GitOps policy for kubectl/helm/flux commands
+        if any(keyword in command for keyword in ("kubectl", "helm", "flux")):
+            gitops_result = validate_gitops_workflow(command)
+            if not gitops_result.allowed:
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=f"GitOps policy violation: {gitops_result.reason}",
+                    suggestions=gitops_result.suggestions,
+                )
+
+        # Flag-dependent classification (sed -i, find -exec, tar -x, etc.)
+        # This supplements mutative_verbs -- it catches flag-dependent mutations
+        # that verb-based detection misses (e.g. "sed" has no mutative verb, but
+        # "sed -i" is mutative).  Runs after blocked_commands and mutative_verbs
+        # to avoid double-classification.
+        #
+        # Git commands are EXCLUDED from the MUTATIVE path here because
+        # detect_mutative_command() already has deliberate git handling.  If it
+        # chose not to block a git command, that decision should be respected.
+        # Git BLOCKED results still fire as a safety net (force push, etc.).
+        flag_result = classify_by_flags(command)
+        if flag_result is not None:
+            if flag_result.outcome == FLAG_BLOCKED:
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=f"Command blocked by flag classifier: {flag_result.reason}",
+                    suggestions=[],
+                )
+            if flag_result.outcome == FLAG_MUTATIVE:
+                # Skip git commands -- mutative_verbs already handles them.
+                if flag_result.command_family.startswith("git_"):
+                    pass  # Fall through to safe-by-elimination
+                else:
+                    reason = (
+                        f"[T3_APPROVAL_REQUIRED] Flag-dependent mutation detected.\n"
+                        f"Command: {command}\n"
+                        f"Flag: {flag_result.matched_pattern} ({flag_result.command_family})\n"
+                        f"Reason: {flag_result.reason}"
+                    )
+                    hook_ask = build_hook_permission_response("ask", reason)
+                    return BashValidationResult(
+                        allowed=False,
+                        tier=SecurityTier.T3_BLOCKED,
+                        reason=f"Mutative flag detected: {flag_result.reason}",
+                        block_response=hook_ask,
+                    )
+
+        # Not blocked, not mutative -> SAFE by elimination
+        return BashValidationResult(
+            allowed=True,
+            tier=SecurityTier.T0_READ_ONLY,
+            reason="Safe by elimination (not blocked, not mutative)",
+        )
+
+    def _validate_compound_command(
+        self,
+        components: List[str],
+        is_subagent: bool = False,
+        session_id: str = "",
+    ) -> BashValidationResult:
+        """Validate a compound command (multiple components)."""
+        logger.info(f"Compound command detected with {len(components)} components")
+
+        component_results: List[BashValidationResult] = []
+        for i, component in enumerate(components, 1):
+            result = self._validate_single_command(
+                component, is_subagent=is_subagent, session_id=session_id,
+            )
+
+            if not result.allowed:
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=(
+                        f"Compound command blocked: component {i}/{len(components)} "
+                        f"'{component[:50]}' is not allowed\n"
+                        f"Reason: {result.reason}"
+                    ),
+                    suggestions=result.suggestions,
+                    block_response=result.block_response,
+                )
+            component_results.append(result)
+
+        # All components validated -- derive highest tier from results already
+        # computed by _validate_single_command (avoids redundant classification).
+        tier_order = ["T0", "T1", "T2", "T3"]
+        highest_tier = max(
+            (r.tier for r in component_results),
+            key=lambda t: tier_order.index(t.value),
+        )
+
+        return BashValidationResult(
+            allowed=True,
+            tier=highest_tier,
+            reason=f"All {len(components)} components validated",
+        )
+
+    def _phase4_check_composition(
+        self, decomposed: DecomposedCommand,
+    ) -> Optional[BashValidationResult]:
+        """Check cross-stage composition patterns (Phase 4).
+
+        Detects dangerous pipe compositions:
+        - Exfiltration: sensitive_read | network_write  -> permanent block
+        - RCE: network_read | exec_sink                 -> permanent block
+        - Obfuscated exec: decode | exec_sink           -> permanent block
+        - File-to-exec: file_read | exec_sink           -> escalate (ask)
+
+        Args:
+            decomposed: Output from StageDecomposer.decompose().
+
+        Returns:
+            BashValidationResult if a composition rule fires, else None.
+        """
+        if not decomposed.stages or len(decomposed.stages) < 2:
+            return None
+
+        # Check whether any stages are pipe-connected.
+        has_pipe = any(s.operator == "|" for s in decomposed.stages)
+        if not has_pipe:
+            return None
+
+        # Build classified composition stages and check rules.
+        comp_stages = build_composition_stages(decomposed.stages)
+        result = check_composition(comp_stages)
+
+        if result.decision == CompositionDecision.BLOCK:
+            return BashValidationResult(
+                allowed=False,
+                tier=SecurityTier.T3_BLOCKED,
+                reason=f"Dangerous pipe composition blocked: {result.reason}",
+            )
+
+        if result.decision == CompositionDecision.ESCALATE:
+            reason = (
+                f"[T3_APPROVAL_REQUIRED] Potentially dangerous pipe composition.\n"
+                f"Pattern: {result.pattern}\n"
+                f"Reason: {result.reason}"
+            )
+            hook_ask = build_hook_permission_response("ask", reason)
+            return BashValidationResult(
+                allowed=False,
+                tier=SecurityTier.T3_BLOCKED,
+                reason=f"Pipe composition requires approval: {result.reason}",
+                block_response=hook_ask,
+            )
+
+        # No composition rule fired — continue to Phase 5.
+        return None
+
+    def _detect_claude_footers(self, command: str) -> bool:
+        """Detect Claude Code attribution footers in command."""
+        for pattern in FORBIDDEN_FOOTER_PATTERNS:
+            if re.search(pattern, command, re.IGNORECASE):
+                return True
+        return False
+
+    def _strip_claude_footers(self, command: str) -> str:
+        """
+        Strip Claude Code attribution footers from a command.
+
+        Removes full lines matching forbidden footer patterns.
+        Works on raw command string regardless of quoting/HEREDOC format.
+        Preserves trailing quote/paren characters that close the commit
+        message (e.g., the closing " in -m "...footer").
+
+        Args:
+            command: Raw command string
+
+        Returns:
+            Command with footer lines removed
+        """
+        # Remove full lines that contain AI attribution patterns.
+        # Each pattern matches the newline + footer content, then uses a
+        # lookahead to stop before any trailing quote/paren/bracket
+        # sequence that closes the command structure.  The captured group
+        # is replaced with empty string, leaving the closing chars intact.
+        footer_line_patterns = [
+            r'\n\s*Co-[Aa]uthored-[Bb]y:\s+(?:Claude|GitHub Copilot|aider|Windsurf|Cursor|Codex|Gemini)[^\n]*?(?=["\')\]]*(?:\n|$))',
+            r'\n\s*Generated with\s+\[?Claude Code\]?[^\n]*?(?=["\')\]]*(?:\n|$))',
+            r'\n\s*🤖\s*Generated with[^\n]*?(?=["\')\]]*(?:\n|$))',
+        ]
+        for pattern in footer_line_patterns:
+            command = re.sub(pattern, '', command, flags=re.IGNORECASE)
+
+        # Clean up trailing whitespace inside quotes/heredoc
+        # Collapse 3+ consecutive newlines to 2
+        command = re.sub(r'\n{3,}', '\n\n', command)
+
+        return command
+
+    def _validate_commit_message(self, command: str) -> BashValidationResult:
+        """
+        Validate git commit message using commit_validator.
+
+        Args:
+            command: Git commit command to validate
+
+        Returns:
+            BashValidationResult with validation status
+        """
+        # Extract commit message from command
+        # Handles both: git commit -m "message" and git commit -m "$(cat <<'EOF'...)"
+        message = self._extract_commit_message(command)
+
+        if not message:
+            # Could not extract message - let it pass, git will handle it
+            return BashValidationResult(
+                allowed=True,
+                tier=SecurityTier.T2_DRY_RUN,
+                reason="Could not extract commit message for validation"
+            )
+
+        # Import validator (lazy import to avoid startup cost)
+        try:
+            import sys
+            from pathlib import Path
+
+            # Import from sibling module (hooks/modules/validation)
+            from ..validation.commit_validator import validate_commit_message
+
+            # Validate message
+            validation = validate_commit_message(message)
+
+            if not validation.valid:
+                # Build suggestions from errors
+                suggestions = []
+                for error in validation.errors:
+                    suggestions.append(f"{error['type']}: {error['fix']}")
+
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=f"Commit message validation failed: {validation.errors[0]['message']}",
+                    suggestions=suggestions[:3]  # Limit to 3 suggestions
+                )
+
+            return BashValidationResult(
+                allowed=True,
+                tier=SecurityTier.T2_DRY_RUN,
+                reason="Commit message validated successfully"
+            )
+
+        except Exception as e:
+            logger.warning(f"Failed to validate commit message: {e}")
+            # If validation fails, allow the command (don't block on validator failure)
+            return BashValidationResult(
+                allowed=True,
+                tier=SecurityTier.T2_DRY_RUN,
+                reason=f"Commit validation skipped (validator error: {e})"
+            )
+
+    def _extract_commit_message(self, command: str) -> Optional[str]:
+        """
+        Extract commit message from git commit command.
+
+        Handles formats:
+        - git commit -m "message"
+        - git commit -m 'message'
+        - git commit -m "$(cat <<'EOF'\nmessage\nEOF\n)"
+        - git commit -m "$(cat <<EOF\nmessage\nEOF\n)"
+
+        Returns:
+            Extracted message or None if cannot extract
+        """
+        # Level 1: HEREDOC pattern (most common in Claude Code)
+        # Handles: <<'EOF', <<EOF, <<"EOF" with flexible whitespace
+        if "<<" in command:
+            heredoc_match = re.search(
+                r"<<['\"]?EOF['\"]?\s*\n(.*?)\n\s*EOF",
+                command, re.DOTALL
+            )
+            if heredoc_match:
+                return heredoc_match.group(1).strip()
+
+        # Level 2: Simple -m "message" or -m 'message' (non-heredoc)
+        match = re.search(r'-m\s+(["\'])(.*?)\1', command, re.DOTALL)
+        if match:
+            msg = match.group(2)
+            # Skip if it's a $(cat... wrapper — heredoc parse failed above
+            if msg.lstrip().startswith("$(cat"):
+                return None
+            return msg.strip()
+
+        return None
+
+def validate_bash_command(
+    command: str,
+    is_subagent: bool = False,
+    session_id: str = "",
+) -> BashValidationResult:
+    """
+    Validate a Bash command (convenience function).
+
+    Args:
+        command: Command to validate
+        is_subagent: True when running in subagent context
+        session_id: Session ID for approval scoping
+
+    Returns:
+        BashValidationResult
+    """
+    validator = BashValidator()
+    return validator.validate(command, is_subagent=is_subagent, session_id=session_id)