@jaguilar87/gaia 5.0.2 → 5.0.4

package/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "description": "Multi-agent orchestration system for Claude Code - DevOps automation toolkit",
   "main": "index.js",
   "type": "module",

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "gaia"
-version = "5.0.2"
+version = "5.0.4"
 description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
 requires-python = ">=3.9"
 license = {text = "MIT"}

package/skills/agent-contract-handoff/SKILL.md

@@ -43,6 +43,7 @@ The fenced `agent_contract_handoff` block. Parsed by `parse_contract` (regex `_R
 | `consolidation_report` | Conditional | required when INPUT set `consolidation_required` / `cross_check_required` / `surface_routing.multi_surface` (`requires_consolidation_report`); else may be `null` |
 | `approval_request` | Conditional | required when `plan_status` is `APPROVAL_REQUEST`; see sub-field table |
 | `loop_state` | Conditional | agentic-loop turns only; `_check_loop_state_blocking` blocks `COMPLETE` when `iteration < max_iterations AND metric < threshold` |
+| `user_facing_summary` | Optional | a brief prose summary written ONCE for the human reader; `parse_user_facing_summary`. The only human-audience field in the contract -- every other field is machine-audience for the orchestrator. On a single-agent `COMPLETE` (N=1) the orchestrator relays it near-verbatim (adapted to the user's language) instead of re-synthesizing `key_outputs`. Absent, or N>1 (multi-agent), the orchestrator falls back to synthesizing `key_outputs`. Purely additive: never required, never rejected. |
 | `memorialize_suggestions` | Optional | structured memory candidates for the user to triage; `parse_memorialize_suggestions` |
 | `memory_suggestions` | Optional | advisory text-only notes (array of strings); `parse_memory_suggestions` |
 | `update_contracts` | Optional | array of `{contract, payload}` for project-context writes; `parse_update_contracts`; see sub-field table |
@@ -67,6 +68,8 @@ The required keys are EXACTLY 7 (`_EVIDENCE_REQUIRED_FIELDS` in `contract_valida
 
 `verification` is a SEPARATE field, NOT one of the 7. It is required ONLY when `plan_status` is `COMPLETE`: it must be a dict and `verification.result` must equal `"pass"`. Missing -> `VERIFICATION_RESULT_REQUIRED_FOR_COMPLETE`; non-pass -> `VERIFICATION_RESULT_MUST_BE_PASS`. For non-COMPLETE statuses `verification` may be absent.
 
+**Audience boundary.** `key_outputs` and every other `evidence_report` key are written for the **orchestrator** -- distilled findings it reasons over to route the next turn. The optional top-level `user_facing_summary` is the **single** field written for the **human**. Keeping the two distinct is what lets the orchestrator relay a human-shaped summary on N=1 without re-synthesizing machine-shaped evidence, and lets it still synthesize from `key_outputs` when the summary is absent or when multiple agents must be consolidated.
+
 ### consolidation_report
 
 Required keys when present (`_CONSOLIDATION_REQUIRED_FIELDS`):

package/skills/agent-response/SKILL.md

@@ -16,7 +16,7 @@ The orchestrator loads this to interpret a returned `agent_contract_handoff` and
 
 ```
 parse_contract(agent_output)  ->  read agent_status.plan_status
-  |- COMPLETE         -> summarize key_outputs + surface verification, then close
+  |- COMPLETE         -> relay user_facing_summary if present & N=1, else summarize key_outputs; surface verification, then close
   |- APPROVAL_REQUEST -> split on approval_id (present: present-approval; absent: plan options)
   |- NEEDS_INPUT      -> AskUserQuestion, then SendMessage the answer
   |- BLOCKED          -> present open_gaps; new dispatch or accept the limitation
@@ -29,7 +29,7 @@ Before any branch runs, the contract must parse. A block that fails `parse_contr
 
 | `plan_status` | Action |
 |---|---|
-| `COMPLETE` | Summarize `key_outputs` in 3-5 bullets AND surface `verification.result` / `verification.details` -- that block is the proof the work landed, and relaying it is what lets the user trust the increment rather than take "done" on faith. Mention `cross_layer_impacts` and `open_gaps` when non-empty. |
+| `COMPLETE` | If `user_facing_summary` is present AND this is a single-agent turn (N=1), relay it near-verbatim -- adapt only to the user's language, do not re-synthesize -- because the subagent already wrote the human-shaped summary and re-summarizing its `key_outputs` only spends tokens to restate what it said. If the field is absent, or N>1 (multiple agents being consolidated), summarize `key_outputs` in 3-5 bullets as before. Either way, surface `verification.result` / `verification.details` -- that block is the proof the work landed, and relaying it is what lets the user trust the increment rather than take "done" on faith. Mention `cross_layer_impacts` and `open_gaps` when non-empty. |
 | `APPROVAL_REQUEST` | Split on `approval_request.approval_id`: present -> load `Skill('orchestrator-present-approval')`; absent -> present the plan with options (execute / modify / cancel) and on execute/modify resume the SAME agent via `SendMessage`. It splits because a hook-issued `approval_id` carries a pending T3 grant that needs the structured consent flow, while a plan-first request only needs direction (`agent-approval-protocol`, combo decision 2). |
 | `NEEDS_INPUT` | `AskUserQuestion` with the options in `next_action`, then `SendMessage` the answer back to resume. |
 | `BLOCKED` | Present `open_gaps` to the user. If they give direction, dispatch a NEW agent addressing the blocker; if they accept the limitation, close the task as incomplete and move on. |
@@ -41,6 +41,8 @@ These ride alongside `plan_status` and carry signal the orchestrator loses if it
 
 **`verification`** -- covered in COMPLETE above. It is required only on `COMPLETE` and its `result` must equal `"pass"` (`VERIFICATION_RESULT_MUST_BE_PASS`, `contract_validator.py`); surface `result` and `details` so the user sees the proof, never just the word "done."
 
+**`user_facing_summary`** -- the one human-audience field (every other field is machine-audience for the orchestrator). On a single-agent `COMPLETE` it is what you relay to the user, near-verbatim and language-adapted, *instead of* re-synthesizing `key_outputs`; that is the whole point -- the subagent wrote the summary once, so re-summarizing duplicates work the user never sees value in. It is optional and additive: when absent, fall back to `key_outputs`; when multiple agents are in flight (N>1), ignore it and synthesize across them, because no single agent's summary speaks for the consolidated result.
+
 **`memorialize_suggestions` / `memory_suggestions`** -- present each entry to the user before closing the turn and persist ONLY on consent. The orchestrator is the sole memory writer; subagents are blocked from curated writes by design so each entry enters the substrate as a named choice. For the curation mechanics -- how to triage, slug, and persist -- load `Skill('memory')` (combo decision 1: the HOW lives in `memory`).
 
 **`ownership_assessment`** (in `consolidation_report`, enum `VALID_OWNERSHIP_ASSESSMENTS`) -- a ROUTING INPUT the orchestrator acts on silently, not a user-facing field. `owned_here` means the output is authoritative; `cross_surface_dependency` or `not_my_surface` means another dispatch may be needed to close the gap. Route on it; do not narrate it (combo decision 4).

package/skills/gaia-patterns/reference.md

@@ -29,7 +29,7 @@ SessionStart emits a one-shot `hookSpecificOutput.additionalContext` manifest (E
 | Package | Files | Purpose |
 |---------|-------|---------|
 | `core/` | `hook_entry`, `paths`, `plugin_mode`, `plugin_setup`, `state`, `stdin` | Entry dispatch, path resolution, mode detection, shared state |
-| `security/` | `blocked_commands`, `mutative_verbs`, `tiers`, `gitops_validator`, `command_semantics`, `approval_grants`, `approval_scopes`, `approval_cleanup`, `approval_constants`, `approval_messages`, `blocked_message_formatter`, `prompt_validator` | T3 gate, blocked commands, approval nonce lifecycle |
+| `security/` | `blocked_commands`, `mutative_verbs`, `tiers`, `command_semantics`, `approval_grants`, `approval_scopes`, `approval_cleanup`, `approval_constants`, `approval_messages`, `blocked_message_formatter`, `prompt_validator` | T3 gate, blocked commands, approval nonce lifecycle |
 | `audit/` | `logger`, `metrics`, `event_detector`, `workflow_auditor`, `workflow_recorder` | Structured logging, metrics collection, workflow audit trail |
 | `tools/` | `bash_validator`, `cloud_pipe_validator`, `shell_parser`, `task_validator`, `hook_response` | Command validation, pipe detection, shell parsing |
 | `context/` | `context_injector`, `context_writer`, `context_freshness`, `contracts_loader`, `compact_context_builder`, `anchor_tracker` | Project-context injection, freshness checks, contract loading |
@@ -254,7 +254,7 @@ The hook invoker is `python3 <script>` rather than executing the script directly
 | Category | Directory | What it tests |
 |----------|-----------|---------------|
 | Prompt regression | `tests/layer1_prompt_regression/` | Routing table, skill content rules, agent frontmatter, agent prompts, security tier consistency, skills cross-reference, context contracts |
-| Hooks | `tests/hooks/modules/` | Security modules (mutative_verbs, blocked_commands, tiers, gitops_validator, approval_grants, approval_scopes, command_semantics), tools (bash_validator, shell_parser, cloud_pipe_validator, task_validator), core (paths, state), context (context_writer) |
+| Hooks | `tests/hooks/modules/` | Security modules (mutative_verbs, blocked_commands, tiers, approval_grants, approval_scopes, command_semantics), tools (bash_validator, shell_parser, cloud_pipe_validator, task_validator), core (paths, state), context (context_writer) |
 | System | `tests/system/` | Directory structure, permissions, agent definitions, configuration, schema compatibility |
 | Tools | `tests/tools/` | context_provider, episodic, pending_updates, deep_merge, review_engine, surface_router |
 | Integration | `tests/integration/` | Context enrichment, subagent lifecycle, subagent stop, nonce approval relay |

package/skills/orchestrator-present-approval/SKILL.md

@@ -71,12 +71,27 @@ Fields above are extracted from the DB-stored canonical payload (`payload_json`
    grant consumed by the first retry (`consume_db_semantic_grant` in
    `gaia/store/writer.py`). A second invocation is a new APPROVAL_REQUEST.
 
-3. **No batch grant.** Legacy `verb_family` was removed; the `COMMAND_SET`
-   replacement has only the CHECK side wired (`match_command_set_grant` is
-   called by `bash_validator`, but `create_command_set_grant` has no production
-   caller). `batch_scope` is ignored. For N commands, expect N approvals.
+3. **Batch grant is `COMMAND_SET` -- one consent, N commands.** Legacy
+   `verb_family` was removed; its replacement, `COMMAND_SET`, is now wired
+   end-to-end (intake, activation, consume). When a subagent emits a plan-first
+   `APPROVAL_REQUEST` carrying a `command_set` of >= 2 `{command, rationale}`
+   items and **no** `approval_id`, the SubagentStop processor
+   (`handoff_persister._intake_command_set_pending`) mints ONE pending
+   `COMMAND_SET` with one `approval_id`. You present that single approval: list
+   **all N commands** in the question body, but use **one** Approve label with
+   **one** `[P-{nonce8}]` suffix -- one consent covers the whole batch. On
+   approval, `activate_db_pending_by_prefix` Step 3b creates a single
+   `COMMAND_SET` grant (60-min TTL); each command is consumed byte-for-byte on
+   its own retry. `batch_scope` is still ignored (the signal is `command_set`).
    See `reference.md` -> "On batch intents".
 
+   You present the batch the subagent chose to send; you do not steer it toward
+   batching. Whether grouping is warranted is the subagent's judgment (known
+   batch, >= 2, friction reduced -- see `subagent-request-approval`). A singular
+   approval arriving where you imagined a batch is not a defect to correct: the
+   default is just-in-time, and a batch you would have manufactured asks the
+   user to consent to commands that may never run.
+
 4. **Re-dispatch, do not resume.** `mode` does not survive a SendMessage resume:
    the resume runs in `default` and re-blocks the next protected operation even
    after the Gaia grant activated. Prefer a fresh re-dispatch with the same
@@ -97,5 +112,5 @@ wording, see `reference.md` -> "GOOD vs BAD Examples", "Option Label Patterns",
 | "I'll skip the [P-...] suffix, it's cosmetic" | The hook extracts the nonce from the label to find the right pending row; without it, targeted activation fails and no grant is created. |
 | "Similar command, slightly different path -- I'll reuse / wrap it" | Grants match the statement signature byte-for-byte. Any wrapper, redirect, flag, or path drift is a different signature and a fresh re-block. |
 | "The same command emitted a new approval_id" | Grants are single-use and consumed on the first retry. A second run is a new APPROVAL_REQUEST -- approve again. |
-| "I'll set batch_scope to approve many at once" | No batch activation exists in current code -- the field is ignored. Each blocked command needs its own approval. |
+| "I'll set batch_scope to approve many at once" | `batch_scope` is ignored -- but a real batch path exists: a plan-first `command_set` (>= 2 items, no `approval_id`) is intaken into ONE pending `COMMAND_SET`. Present that single approval (N commands shown, one `[P-...]` nonce, one consent), not N separate approvals. |
 | "I can paraphrase a field before relaying" | The fingerprint covers all 7 sealed fields; any modification raises `ChainTamperError` in Step 0 and the presentation is refused. |

package/skills/orchestrator-present-approval/reference.md

@@ -107,32 +107,49 @@ contain `[P-<hex>]`. Reject labels never carry a nonce. The captured hex is the
 `get_pending(all_sessions=True)` and selects the one whose `id` starts with
 `P-{prefix}`.
 
-## On batch intents -- there is no multi-use grant
+## On batch intents -- the COMMAND_SET grant (one consent, N commands)
 
 The old `verb_family` design (one approval covering many commands of the same
 `base_cmd + verb`) **was removed**. The module docstring in
 `hooks/modules/security/approval_grants.py` is explicit: "The legacy verb_family
 path has been removed."
 
-The intended replacement is the `COMMAND_SET` grant: an explicit list of
+Its replacement is the `COMMAND_SET` grant: an explicit list of
 `{command, rationale}` items, each matched **byte-for-byte** (D10: no whitespace
 normalization, no quote canonicalization, no shell expansion) and consumed
 individually (`create_command_set_grant` and `match_command_set_grant` in
 `approval_grants.py`).
 
-**Current state of the code:** only the CHECK side is wired. `bash_validator`
-(`hooks/modules/tools/bash_validator.py`) calls `match_command_set_grant()` and
-consumes a matched item, but **no production path calls
-`create_command_set_grant()`** -- it exists only in the module and its tests.
-The ElicitationResult / adapter activation paths (`hooks/elicitation_result.py`,
-`hooks/adapters/claude_code.py`) contain no "batch", "verb_family", "multi_use",
-or "command_set" handling; they only call `activate_db_pending_by_prefix()`,
-which creates a single-use `SCOPE_SEMANTIC_SIGNATURE` grant.
-
-**Practical consequence:** putting the word "batch" in a label, or a `batch_scope`
-field in an `approval_request`, does nothing. Each blocked command produces its
-own single-use semantic grant and its own approval. For a sweep of N commands,
-expect N approvals until the COMMAND_SET create path is wired.
+**Current state of the code: all three sides are wired -- intake, activation,
+consume.** It is a **plan-first** flow: the subagent declares the batch up-front
+by emitting an `APPROVAL_REQUEST` whose `approval_request` carries a
+`command_set` list and **no** `approval_id`.
+
+- **Intake.** The SubagentStop processor
+  `hooks/modules/agents/handoff_persister.py` ->
+  `_intake_command_set_pending()` reads the `command_set`; when it holds **>= 2**
+  items it calls `gaia.approvals.store.insert_requested()` with a payload that
+  contains the `command_set` key, minting **exactly ONE** pending `COMMAND_SET`
+  approval with one `approval_id`. A set of `<= 1` item is declined (no
+  COMMAND_SET is minted for one command).
+- **Activation.** When the user approves, `activate_db_pending_by_prefix()`
+  (`hooks/modules/security/approval_grants.py`) reads `payload["command_set"]`,
+  and because it has > 1 item branches at **Step 3b** into
+  `create_command_set_grant()`, inserting ONE `COMMAND_SET` grant row (status
+  `PENDING`, `command_set_json` holding the whole set, 60-min TTL via
+  `DEFAULT_COMMAND_SET_TTL_MINUTES`) instead of a singular
+  `SCOPE_SEMANTIC_SIGNATURE` grant.
+- **Consume.** On each retry, `bash_validator` calls `match_command_set_grant()`
+  (byte-for-byte index match), then `mark_command_set_item_consumed()`; a
+  consumed index never matches again (replay protection), and when every index
+  is consumed the grant flips to `CONSUMED`.
+
+**Practical consequence:** a `batch_scope` field still does nothing -- the signal
+is `command_set`. To approve a sweep of N related commands under one consent,
+present the single `COMMAND_SET` approval the intake minted: show **all N
+commands** in the question body, with **one** Approve label carrying **one**
+`[P-{nonce8}]` suffix. The user gives one consent; each command then runs on its
+own retry within the 60-minute window. You do NOT issue N separate approvals.
 
 ## Grant Activation Mechanics
 

package/skills/security-tiers/SKILL.md

@@ -17,7 +17,11 @@ security-tiers classifies every operation into four tiers so an agent knows whet
 | **T0** | Read-only; observes state, changes nothing | No | get, list, describe, show, logs, status |
 | **T1** | Local validation; no remote calls, no state | No | validate, lint, fmt, check |
 | **T2** | Simulation / dry-run; may read remote, never writes | No | plan, diff, dry-run, template |
-| **T3** | State-mutating; creates, updates, or destroys | **Yes** | apply, create, delete, commit, push, deploy |
+| **T3** | State-mutating; creates, updates, or destroys | **Yes** | apply, create, delete, push, deploy |
+
+`git commit` and `git add` are **not** T3 -- they are local-only operations (they touch the working tree and local refs, never remote state), so they classify as safe by elimination. Only `git push` mutates remote state and is T3. This matches `GIT_LOCAL_SAFE_SUBCOMMANDS` in `mutative_verbs.py`, where `commit` and `add` are listed as local-safe.
+
+**T3 gates a direction, not a category of verb.** An operation needs consent because it moves the system toward *more* capability (it grants) or *less* recoverability (it destroys). An operation that only moves the other way -- that *reduces* capability already granted -- does not need consent, because the worst it can do is take back power that was given. So within Gaia's own consent layer, `gaia approvals revoke|reject|reject-all|clean` are **not** T3: they only revoke or discard grants Gaia itself issued, never reaching outside the local approval store. The asymmetry is deliberate -- `gaia approvals approve` *grants* capability without the AskUserQuestion flow, so it stays T3. This is anchored to the `gaia approvals` group in `CONSENT_REDUCING_SUBCOMMAND_EXCEPTIONS` (`mutative_verbs.py`), not generalized to every CLI's "revoke" -- a cloud IAM revoke is a real remote mutation and remains T3.
 
 ## Classification heuristic
 

package/skills/security-tiers/reference.md

@@ -36,7 +36,9 @@ Read on-demand by infrastructure agents. Not injected automatically.
 - `kubectl apply -f manifest.yaml`
 - `helm upgrade` (without `--dry-run`)
 - `flux reconcile` (write operations)
-- `git commit`, `git push` (any branch)
+- `git push` (any branch) -- mutates remote state
+
+Note: `git commit` and `git add` are **not** T3. They are local-only (working tree + local refs, never remote), classified safe by elimination via `GIT_LOCAL_SAFE_SUBCOMMANDS` in `mutative_verbs.py`. Only `git push` reaches remote state.
 
 ## Edge Cases