@jaguilar87/gaia 5.0.2 → 5.0.4

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

@@ -151,10 +151,10 @@ MUTATIVE_VERBS: FrozenSet[str] = frozenset({
     "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",
+    # NOTE: "put" and "patch" already appear under Modification above, and
+    # "uninstall" under Deletion/removal -- so only "post" is new here.
+    "post",
 })
 
 SIMULATION_VERBS: FrozenSet[str] = frozenset({
@@ -283,6 +283,12 @@ COMMAND_SUBCOMMAND_TIER_EXCEPTIONS: Dict[Tuple[str, str], str] = {
     # `gaia ac <verb>` (add/remove/edit/show/list/set-status): local acceptance-
     # criteria bookkeeping — reversible, no external effects.
     ("gaia", "ac"): CATEGORY_READ_ONLY,
+    # `gaia plan <verb>` (save/edit/show/list/set-status): local planning
+    # bookkeeping in the plan store — reversible, no external effects.  Anchored
+    # here (not left to the SIMULATION_VERBS['plan'] lexical collision) so the
+    # exemption is explicit and carries the same DENY-verb guard as `gaia brief`:
+    # `gaia plan delete` (whole-record destruction) stays T3.
+    ("gaia", "plan"): CATEGORY_READ_ONLY,
 }
 
 # Verbs that stay gated even under an excepted group above.  The exception
@@ -294,6 +300,37 @@ COMMAND_SUBCOMMAND_EXCEPTION_DENY_VERBS: FrozenSet[str] = frozenset({
 })
 
 
+# ============================================================================
+# PRINCIPLE: consent-REDUCING operations are not T3.
+# ----------------------------------------------------------------------------
+# An operation requires T3 approval because it GRANTS capability or DESTROYS
+# state — it moves the system toward *more* power or *less* recoverability, the
+# directions that need informed consent.  An operation that REVOKES, REJECTS,
+# or CLEANS a consent grant Gaia itself issued moves in the opposite direction:
+# it can only REDUCE the capability already granted.  It never grants anything
+# and never reaches outside the local approval store.  Gating it creates an
+# absurd loop — you would need an approval to clean up approvals.
+#
+# So: within Gaia's own consent layer (`gaia approvals ...`), verbs that REDUCE
+# consent are exempted to read-only; the one verb that GRANTS capability
+# (`approve`) is deliberately NOT in this set and stays T3.  That asymmetry is
+# the whole point: `approve` hands out capability without the AskUserQuestion
+# flow, so it must remain gated; `revoke`/`reject`/`reject-all`/`clean` only
+# take capability back, so they must not be.
+#
+# This is anchored to (base_cmd, group) so it applies ONLY to Gaia's own
+# consent store, not to any other CLI's notion of "revoke"/"reject" (e.g. a
+# cloud IAM revoke is a real remote mutation and must stay T3).
+#
+# Key:   (base_cmd, subcommand-group)  — e.g. ("gaia", "approvals").
+# Value: frozenset of consent-REDUCING verbs under that group that are exempt.
+CONSENT_REDUCING_SUBCOMMAND_EXCEPTIONS: Dict[Tuple[str, str], FrozenSet[str]] = {
+    ("gaia", "approvals"): frozenset({
+        "revoke", "reject", "reject-all", "clean",
+    }),
+}
+
+
 # ============================================================================
 # Inline Code Detection — Language-Agnostic 3-Layer Approach
 # ============================================================================
@@ -1159,10 +1196,30 @@ def detect_mutative_command(command: str) -> MutativeResult:
             group_verb.split("-", 1)[0] in COMMAND_SUBCOMMAND_EXCEPTION_DENY_VERBS
             or group_verb in COMMAND_SUBCOMMAND_EXCEPTION_DENY_VERBS
         )
-        if (
-            subcommand_key in COMMAND_SUBCOMMAND_TIER_EXCEPTIONS
-            and not verb_is_destructive
-        ):
+        if subcommand_key in COMMAND_SUBCOMMAND_TIER_EXCEPTIONS:
+            if verb_is_destructive:
+                # Whole-record destruction (e.g. `gaia plan delete`) must stay
+                # T3 even inside an excepted group.  Anchor it MUTATIVE here
+                # instead of falling through to Step 4: the group token itself
+                # (`plan`) collides lexically with SIMULATION_VERBS['plan'], so
+                # the verb scanner would otherwise mis-classify the whole
+                # command as SIMULATION and silently un-gate the delete.  This
+                # explicit return is what makes `gaia plan delete` behave like
+                # `gaia brief delete` (where `brief` has no such collision).
+                dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+                return MutativeResult(
+                    is_mutative=True,
+                    category=CATEGORY_MUTATIVE,
+                    verb=group_verb.split("-", 1)[0],
+                    dangerous_flags=dangerous_flags,
+                    cli_family=family,
+                    confidence="high",
+                    reason=(
+                        f"Whole-record destruction "
+                        f"'{base_cmd} {semantics.non_flag_tokens[0]} {group_verb}' "
+                        f"stays T3 despite the local bookkeeping exception"
+                    ),
+                )
             dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
             if not dangerous_flags:
                 target_category = COMMAND_SUBCOMMAND_TIER_EXCEPTIONS[subcommand_key]
@@ -1179,6 +1236,41 @@ def detect_mutative_command(command: str) -> MutativeResult:
                     ),
                 )
 
+    # --- Step 3f: Consent-reducing operations are not T3 (anchored) ---
+    # Within Gaia's own consent layer (`gaia approvals ...`), verbs that REDUCE
+    # consent (revoke/reject/reject-all/clean) can only take back capability
+    # already granted — they never grant anything and never reach outside the
+    # local approval store, so they are not T3.  The one consent-GRANTING verb
+    # (`approve`) is deliberately absent from CONSENT_REDUCING_SUBCOMMAND_
+    # EXCEPTIONS and falls through to Step 4, where it stays MUTATIVE/T3.  That
+    # asymmetry is the principle: granting capability needs consent, reducing it
+    # does not.  Anchored to (base_cmd, group) so it never relaxes another CLI's
+    # "revoke" (e.g. a cloud IAM revoke is a real remote mutation, still T3).
+    # Dangerous flags are still scanned so a slip like `--force` re-gates.
+    if semantics.non_flag_tokens:
+        consent_group_key = (base_cmd, semantics.non_flag_tokens[0])
+        consent_verb = (
+            semantics.non_flag_tokens[1]
+            if len(semantics.non_flag_tokens) > 1 else ""
+        )
+        reducing_verbs = CONSENT_REDUCING_SUBCOMMAND_EXCEPTIONS.get(consent_group_key)
+        if reducing_verbs is not None and consent_verb in reducing_verbs:
+            dangerous_flags = _scan_dangerous_flags(tokens, base_cmd)
+            if not dangerous_flags:
+                return MutativeResult(
+                    is_mutative=False,
+                    category=CATEGORY_READ_ONLY,
+                    verb=consent_verb,
+                    cli_family=family,
+                    confidence="high",
+                    reason=(
+                        f"Consent-reducing operation "
+                        f"'{base_cmd} {semantics.non_flag_tokens[0]} {consent_verb}' "
+                        f"only revokes/rejects capability already granted — "
+                        f"not state-granting, so not T3"
+                    ),
+                )
+
     # --- 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):

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

@@ -32,7 +32,6 @@ 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,
@@ -96,12 +95,35 @@ class BashValidationResult:
 
 
 # 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.
+# Covers Claude Code, GitHub Copilot, Aider, Windsurf, Codex, Gemini, the
+# Anthropic model family (Opus/Sonnet/Haiku), and any future tool using the
+# Co-authored-by git trailer convention.
+#
+# IMPORTANT: this list is the DETECTOR (`_detect_claude_footers`). It MUST stay
+# aligned with the line patterns in `_strip_claude_footers` -- if the stripper
+# can remove a footer the detector cannot see, the strip never fires (the
+# early-normalization guard only strips when the detector returns True). Every
+# footer shape the stripper removes has a corresponding detector entry here.
+#
+# None of these patterns anchor on a newline, so they also catch footers that
+# arrive in a SECOND `-m "..."` argument (no preceding newline) -- the detector
+# fires, and the stripper's `-m`-aware branch removes them.
 FORBIDDEN_FOOTER_PATTERNS = [
     r"Generated with\s+Claude Code",
     r"Generated with\s+\[?Claude Code\]?",
+    # Bare robot-emoji "Generated with ..." line (e.g. "🤖 Generated with ...")
+    # WITHOUT requiring the literal "Claude Code" after it -- the stripper has
+    # always removed this shape; the detector now sees it too.
+    r"🤖\s*Generated with",
+    # Robot emoji on its own is a strong AI-attribution signal.
+    r"🤖",
     r"Co-Authored-By:\s+Claude\b",
+    # Anthropic model family attributed via Co-Authored-By / Co-authored-with.
+    r"Co-[Aa]uthored-(?:[Bb]y|[Ww]ith):[^\n]*\bOpus\b",
+    r"Co-[Aa]uthored-(?:[Bb]y|[Ww]ith):[^\n]*\bSonnet\b",
+    r"Co-[Aa]uthored-(?:[Bb]y|[Ww]ith):[^\n]*\bHaiku\b",
+    # "Approved-by:" attribution trailer.
+    r"Approved-by:",
     r"Co-authored-by:\s+GitHub Copilot\b",
     r"Co-authored-by:\s+aider\b",
     r"Co-authored-by:\s+Windsurf\b",
@@ -466,7 +488,7 @@ class BashValidator:
         #   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)
+        #        (mutative_verbs, safe-by-elimination)
         # ================================================================
 
         # 3a. Blocked commands check on FULL command (exit 2).
@@ -624,7 +646,7 @@ class BashValidator:
         if result.is_mutative:
             # Check for a DB-backed command_set grant first (M3 path).
             # Byte-for-byte match per D10: no normalization.
-            cs_match = match_command_set_grant(command, session_id=session_id)
+            cs_match = match_command_set_grant(command)
             if cs_match is not None:
                 cs_approval_id, cs_index = cs_match
                 try:
@@ -732,17 +754,6 @@ class BashValidator:
                     agent_type=agent_type,
                 )
 
-        # 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
@@ -775,7 +786,7 @@ class BashValidator:
                     # never honoured and the command re-blocks unconditionally on
                     # every retry (the flag path never reaches the matcher).  The
                     # consume + return semantics replicate the verb branch exactly.
-                    cs_match = match_command_set_grant(command, session_id=session_id)
+                    cs_match = match_command_set_grant(command)
                     if cs_match is not None:
                         cs_approval_id, cs_index = cs_match
                         try:
@@ -1004,32 +1015,77 @@ class BashValidator:
 
     def _strip_claude_footers(self, command: str) -> str:
         """
-        Strip Claude Code attribution footers from a command.
+        Strip AI attribution footers from a commit 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").
 
+        Covers, kept ALIGNED with FORBIDDEN_FOOTER_PATTERNS (the detector):
+          - Co-authored-by / Co-authored-with: Claude, Copilot, aider,
+            Windsurf, Cursor, Codex, Gemini, and the Anthropic model family
+            (Opus / Sonnet / Haiku)
+          - "Generated with [Claude Code]" and the bare "🤖 Generated with ..."
+          - a bare robot emoji 🤖 line
+          - "Approved-by:" trailers
+        Both newline-anchored footer LINES and footers carried in a SECOND
+        ``-m "..."`` argument (no preceding newline) are handled.
+
+        LIMITATION -- ``git commit -F <file>`` / ``--file=<file>``: when the
+        message body lives in a file, the footer is NOT in the command string
+        the PreToolUse hook receives. This stripper CANNOT see or remove it,
+        and deliberately does NOT read the referenced file (reading arbitrary
+        paths from a hook would be an unbounded side effect and a new attack
+        surface). Footer suppression for ``-F`` commits is therefore out of
+        scope here and must be enforced elsewhere (e.g. a commit-msg git hook).
+
         Args:
             command: Raw command string
 
         Returns:
             Command with footer lines removed
         """
-        # Remove full lines that contain AI attribution patterns.
+        # Author/model alternation reused across line- and -m-shaped patterns.
+        _authors = (
+            r"Claude|GitHub Copilot|aider|Windsurf|Cursor|Codex|Gemini"
+            r"|Opus|Sonnet|Haiku"
+        )
+
+        # (1) 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*Co-[Aa]uthored-(?:[Bb]y|[Ww]ith):\s+(?:' + _authors + r')[^\n]*?(?=["\')\]]*(?:\n|$))',
+            # Co-authored-* lines naming an Anthropic model anywhere on the line.
+            r'\n\s*Co-[Aa]uthored-(?:[Bb]y|[Ww]ith):[^\n]*?\b(?:Opus|Sonnet|Haiku)\b[^\n]*?(?=["\')\]]*(?:\n|$))',
+            r'\n\s*Approved-by:[^\n]*?(?=["\')\]]*(?:\n|$))',
             r'\n\s*Generated with\s+\[?Claude Code\]?[^\n]*?(?=["\')\]]*(?:\n|$))',
             r'\n\s*🤖\s*Generated with[^\n]*?(?=["\')\]]*(?:\n|$))',
+            # Bare robot-emoji line (emoji not followed by "Generated with").
+            r'\n\s*🤖[^\n]*?(?=["\')\]]*(?:\n|$))',
         ]
         for pattern in footer_line_patterns:
             command = re.sub(pattern, '', command, flags=re.IGNORECASE)
 
+        # (2) Remove footers carried in a SEPARATE ``-m "..."`` / ``-m '...'``
+        # argument.  Repeated ``-m`` flags are concatenated by git as separate
+        # paragraphs, so an attribution footer often arrives as
+        #   git commit -m "real message" -m "Co-Authored-By: ... Opus"
+        # with NO preceding newline -- the line patterns above cannot see it.
+        # Drop the entire trailing ``-m "<footer>"`` flag+value when its value
+        # is (essentially) just an attribution footer.
+        m_footer_patterns = [
+            r'''\s+-m\s+(["'])\s*Co-[Aa]uthored-(?:[Bb]y|[Ww]ith):\s+(?:''' + _authors + r''')[^"']*\1''',
+            r'''\s+-m\s+(["'])\s*Approved-by:[^"']*\1''',
+            r'''\s+-m\s+(["'])\s*🤖[^"']*\1''',
+            r'''\s+-m\s+(["'])\s*Generated with\s+\[?Claude Code\]?[^"']*\1''',
+        ]
+        for pattern in m_footer_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)
@@ -1222,6 +1278,7 @@ def _build_sealed_payload(
     verb: str,
     category: str,
     agent_type: str = "",
+    command_set: list | None = None,
 ) -> dict:
     """Build a sealed_payload dict from hook-intercepted command context.
 
@@ -1229,16 +1286,51 @@ def _build_sealed_payload(
     and calls store.insert_requested(). The 7 D13 fields are populated from
     what is available at intercept time.
 
+    Single vs. multi-command (COMMAND_SET):
+        By default this builds a SINGLE-command payload -- ``commands`` is
+        ``[command]`` and no ``command_set`` key is present, so activation
+        mints a single-use SCOPE_SEMANTIC_SIGNATURE grant.
+
+        When ``command_set`` is supplied (a list of ``{command, rationale}``
+        dicts representing more than one command the agent wants under ONE
+        consent), the payload additionally carries a ``command_set`` key
+        verbatim and ``commands`` lists every command string in the set. This
+        is the signal ``activate_db_pending_by_prefix`` reads to branch into
+        ``create_command_set_grant`` instead of degrading to a single command.
+        The set is NOT collapsed -- every item survives into the grant.
+
     Args:
-        command: The full Bash command string that was blocked.
+        command: The full Bash command string that was blocked (the primary /
+            first command; used for ``exact_content`` and the singular display).
         verb: The detected mutative verb (e.g. 'push', 'delete').
         category: The verb category string (e.g. 'MUTATIVE').
         agent_type: Name of the originating agent (may be empty).
+        command_set: Optional list of ``{command, rationale}`` dicts. When it
+            contains more than one item, the payload becomes a COMMAND_SET
+            envelope. A list with a single item (or None) keeps the singular
+            semantic-signature behaviour.
 
     Returns:
-        Dict with the 7 sealed_payload fields from D13.
+        Dict with the 7 sealed_payload fields from D13, plus an optional
+        ``command_set`` key when a multi-command set was supplied.
     """
-    return {
+    # Normalize the command_set into the canonical [{command, rationale}, ...]
+    # shape and decide whether this is a genuine multi-command envelope. A set
+    # of length <= 1 is NOT multi-command -- it stays the singular path so we
+    # never mint a COMMAND_SET grant for one command.
+    normalized_set: list = []
+    if command_set:
+        for item in command_set:
+            if isinstance(item, dict) and item.get("command"):
+                normalized_set.append(
+                    {
+                        "command": item["command"],
+                        "rationale": item.get("rationale", ""),
+                    }
+                )
+    is_command_set = len(normalized_set) > 1
+
+    payload = {
         "operation": f"{category} command intercepted: {verb}",
         "exact_content": command,
         "scope": command.split()[0] if command.strip() else "unknown",
@@ -1250,9 +1342,18 @@ def _build_sealed_payload(
             if agent_type
             else f"A {category.lower()} ({verb}) command requires user approval per T3 policy."
         ),
-        "commands": [command],
+        "commands": (
+            [it["command"] for it in normalized_set] if is_command_set else [command]
+        ),
     }
 
+    if is_command_set:
+        # Carry the full {command, rationale} set verbatim. This is the
+        # multi-command signal the activation path branches on.
+        payload["command_set"] = normalized_set
+
+    return payload
+
 
 def decide_t3_outcome(
     command: str,

package/gaia/state/transitions.py

@@ -10,10 +10,10 @@ The Contract workflow transitions live in
 here for symmetry; the brief lifecycle transitions live in
 ``gaia.briefs.store._LEGAL_TRANSITIONS`` and are likewise imported.
 
-The plan and task lifecycle transitions are defined here directly (the
-underlying tables ``plans`` and ``tasks`` have no CLI surface yet -- a
-separate brief, ``cli-completion``, will add ``gaia plan`` and
-``gaia task`` commands that consume these helpers).
+The plan and task lifecycle transitions are defined here directly. The
+``gaia plan`` and ``gaia task`` commands (``bin/cli/plan.py`` and
+``bin/cli/task.py``) consume these helpers when driving the ``plans`` and
+``tasks`` lifecycle.
 """
 
 from __future__ import annotations

package/gaia/store/writer.py

@@ -2822,6 +2822,62 @@ def list_approval_grants(
         con.close()
 
 
+def list_command_set_grants_agnostic(
+    *,
+    status: str = "PENDING",
+    limit: int = 100,
+    db_path: Path | None = None,
+) -> list[dict]:
+    """List COMMAND_SET grants WITHOUT a session_id constraint (Brief 71).
+
+    This is the COMMAND_SET analogue of the session-agnostic lookup that
+    ``check_db_semantic_grant`` performs for the SINGULAR (semantic-signature)
+    grant. The block-approve-retry flow legitimately spans sessions -- a
+    command is blocked under the subagent session, the user approves under the
+    orchestrator session, and the consuming retry runs under whichever session
+    (or none -- CLAUDE_SESSION_ID is not guaranteed to be exported into the bash
+    subprocess, where ``get_session_id()`` then falls back to the literal
+    ``"default"``). A session_id filter therefore never matches the grant the
+    approval created, which is exactly the consumption-bypass bug this function
+    fixes.
+
+    The security boundary is preserved WITHOUT a session_id constraint, by the
+    same conjunction of session-agnostic facts the singular path relies on
+    (mirrors the comment in ``check_db_semantic_grant``):
+      * the byte-for-byte command match (applied by the caller against each
+        unconsumed command_set item) binds the grant to THIS command's exact
+        intent;
+      * status='PENDING' plus per-index ``consumed_indexes_json`` is the
+        single-use replay guard -- a fully consumed grant flips to CONSUMED and
+        no longer matches, and an already-consumed index is skipped;
+      * expires_at is the TTL -- a stale grant past its window is skipped.
+    None of these depend on which session is asking, so dropping the session_id
+    filter widens nothing the other checks do not already gate. It only lets the
+    legitimate cross-session (or empty-session) retry succeed.
+
+    Args:
+        status: Status to filter on (default 'PENDING').
+        limit: Maximum rows to return.
+        db_path: Optional explicit DB path (used by tests).
+
+    Returns:
+        List of dicts keyed by column name, ordered by created_at DESC.
+    """
+    con = _connect(db_path)
+    try:
+        rows = con.execute(
+            "SELECT * FROM approval_grants "
+            "WHERE scope = 'COMMAND_SET' AND status = ? "
+            "ORDER BY created_at DESC LIMIT ?",
+            (status, limit),
+        ).fetchall()
+        return [dict(r) for r in rows]
+    except Exception:
+        return []
+    finally:
+        con.close()
+
+
 # ---------------------------------------------------------------------------
 # Public API: insert_semantic_grant / check_db_semantic_grant /
 #             consume_db_semantic_grant (CHECK-side DB cutover, Brief 71)

package/hooks/modules/README.md

@@ -45,8 +45,7 @@ modules/
 │   ├── approval_constants.py # Approval system constants
 │   ├── approval_messages.py  # Approval denial message formatting
 │   ├── approval_scopes.py   # Approval scope definitions
-│   ├── command_semantics.py  # Command semantic analysis
-│   └── gitops_validator.py # kubectl/helm/flux validation
+│   └── command_semantics.py  # Command semantic analysis
 │
 ├── tools/                # Tool-specific validators
 │   ├── __init__.py
@@ -179,8 +178,7 @@ bash_validator checks commands in this order (short-circuit on first match):
 3. **Commit message validation** — conventional commits enforcement
 4. **Cloud pipe/redirect/chain check** (cloud_pipe_validator.py) — corrective deny
 5. **Mutative verbs** (mutative_verbs.py) — CLI-agnostic verb detector, native `ask` dialog
-6. **GitOps validation** (gitops_validator.py) — kubectl/helm/flux policy enforcement
-7. **Everything else** — SAFE by elimination (auto-approved)
+6. **Everything else** — SAFE by elimination (auto-approved)
 
 ### Tier Classification
 - **T0**: Read-only (get, list, describe, show)

package/hooks/modules/agents/contract_validator.py

@@ -19,6 +19,7 @@ Provides:
     - parse_rollback_executed(): Parse rollback_executed clause (advisory)
     - parse_context_consumption(): Parse context_consumption clause (advisory)
     - parse_memory_suggestions(): Parse memory_suggestions clause (advisory)
+    - parse_user_facing_summary(): Parse user_facing_summary clause (advisory)
 """
 
 import json
@@ -655,6 +656,23 @@ def parse_memory_suggestions(contract: dict) -> List[str]:
     return [str(item) for item in raw if item is not None]
 
 
+def parse_user_facing_summary(contract: dict) -> Optional[str]:
+    """Parse the optional top-level ``user_facing_summary`` clause (advisory).
+
+    The single human-audience field in the contract: a short prose summary the
+    subagent writes once for the user. The orchestrator relays it near-verbatim
+    on a single-agent COMPLETE (N=1) instead of re-synthesizing ``key_outputs``.
+
+    Strictly additive and advisory -- the validator never rejects based on this
+    field. Returns the trimmed string when present and non-empty, else None.
+    """
+    raw = contract.get("user_facing_summary")
+    if not isinstance(raw, str):
+        return None
+    text = raw.strip()
+    return text or None
+
+
 def extract_plan_status_from_output(agent_output: str) -> str:
     """Extract the effective plan_status string from agent output.