@jaguilar87/gaia 5.0.2 → 5.0.5

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.
 

package/hooks/modules/agents/handoff_persister.py

@@ -10,11 +10,187 @@ arise if the adapter imported _persist_handoff directly from subagent_stop
 (which itself imports from the adapter's dependency tree).
 """
 
+from __future__ import annotations
+
 import logging
 
 logger = logging.getLogger(__name__)
 
 
+def _normalize_command_set(raw) -> list:
+    """Coerce a raw ``command_set`` into the canonical ``[{command, rationale}]``.
+
+    Mirrors the normalization in ``bash_validator._build_sealed_payload`` and
+    ``approval_grants.activate_db_pending_by_prefix`` so the intake writes the
+    exact shape the activation/consume sides expect. Items without a non-empty
+    ``command`` are dropped; ``rationale`` defaults to "".
+    """
+    out: list = []
+    if isinstance(raw, list):
+        for item in raw:
+            if isinstance(item, dict) and item.get("command"):
+                out.append(
+                    {
+                        "command": item["command"],
+                        "rationale": item.get("rationale", ""),
+                    }
+                )
+    return out
+
+
+def _filter_mutative_command_set(items: list) -> list:
+    """Keep only the command_set items whose command is mutative/T3.
+
+    The consume side (``bash_validator._validate_single_command``) gates the
+    whole COMMAND_SET match path on ``detect_mutative_command(command).is_mutative``:
+    a command that the matcher does not see as mutative NEVER reaches
+    ``match_command_set_grant`` and its index is therefore NEVER consumed. If
+    such a command is included in the grant's ``command_set``, ``len(consumed)``
+    can never reach ``len(command_set)`` and the grant is stuck PENDING forever
+    (it never flips to CONSUMED). To stay in lockstep with the consume gate, the
+    intake filters with the EXACT same predicate, dropping non-mutative commands
+    (e.g. ``touch``, ``ls``, ``cat``) before the grant is ever minted.
+
+    Items that fail to classify (import error, unexpected exception) are kept --
+    failing open here is safer than silently dropping a command from a consent
+    batch the user is about to approve.
+    """
+    try:
+        from modules.security.mutative_verbs import detect_mutative_command
+    except ImportError:
+        import pathlib as _pl
+        import sys as _sys
+
+        _hooks_root = _pl.Path(__file__).resolve().parent.parent.parent
+        _sys.path.insert(0, str(_hooks_root))
+        from modules.security.mutative_verbs import detect_mutative_command
+
+    kept: list = []
+    for item in items:
+        command = item.get("command", "")
+        try:
+            if detect_mutative_command(command).is_mutative:
+                kept.append(item)
+        except Exception:
+            # Fail open: if classification raises, keep the item rather than
+            # silently dropping a command from the user's consent batch.
+            kept.append(item)
+    return kept
+
+
+def _intake_command_set_pending(
+    approval_req: dict,
+    *,
+    agent_id,
+    session_id: str,
+) -> str | None:
+    """INTAKE bridge: plan-first COMMAND_SET envelope -> ONE pending row.
+
+    When a subagent emits an ``APPROVAL_REQUEST`` whose ``approval_request``
+    carries a ``command_set`` of >= 2 ``{command, rationale}`` items and NO
+    ``approval_id`` (plan-first: the batch is declared up-front, before any
+    command was attempted/blocked), this persists exactly ONE pending approval
+    whose ``payload_json`` contains the ``command_set`` key. That is the signal
+    ``activate_db_pending_by_prefix`` reads (Step 3b) to branch into
+    ``create_command_set_grant`` on user approval.
+
+    Mutative filtering (Thread a): the command_set is first reduced to ONLY the
+    commands the consume side will treat as mutative/T3 -- see
+    ``_filter_mutative_command_set``. Non-mutative commands (``touch``, ``ls``,
+    ...) never reach the bash_validator matcher, so leaving them in the grant
+    would strand its ``consumed_indexes_json`` short of completion and pin the
+    grant at PENDING forever. After filtering:
+
+      * >= 2 mutative items  -> mint the COMMAND_SET over exactly those items.
+      * exactly 1 mutative   -> NOT a batch. Return None; the caller falls
+        through to the singular ``approval_id`` path and the lone command is
+        gated by the normal hook-block / SCOPE_SEMANTIC_SIGNATURE flow when the
+        agent attempts it. We deliberately do NOT degrade-to-singular here: this
+        function's contract is "mint a COMMAND_SET or stand aside", and the
+        singular flow is owned end-to-end by the hook block path -- minting a
+        singular row from here would duplicate that ownership.
+      * 0 mutative           -> nothing to approve. Return None (no pending).
+
+    A raw ``command_set`` of <= 1 item is likewise not a batch and returns None
+    before filtering, preserving the original contract (never mint for one
+    command, never degrade a batch the other way) and the working plan-first
+    flow for genuine multi-command mutative batches.
+
+    Returns the minted ``approval_id`` (``P-{uuid4hex}``) on success, or None
+    when this is not a plan-first command_set envelope (no action taken).
+    """
+    if not isinstance(approval_req, dict):
+        return None
+    # Plan-first is defined by command_set present AND no approval_id. A request
+    # that already carries an approval_id was minted by the hook block path; it
+    # is the singular flow and must not be re-intaken here.
+    if approval_req.get("approval_id"):
+        return None
+
+    raw_items = _normalize_command_set(approval_req.get("command_set"))
+    if len(raw_items) < 2:
+        # 0 or 1 item: not a batch. Singular path owns it.
+        return None
+
+    # Reduce to the mutative/T3 commands only -- the exact predicate the consume
+    # side uses to decide whether a command reaches the COMMAND_SET matcher.
+    command_set_items = _filter_mutative_command_set(raw_items)
+    if len(command_set_items) < 2:
+        # After filtering there is no batch left: either every command was
+        # non-mutative (0 -> nothing to approve) or just one mutative command
+        # remained (1 -> singular path owns it). Either way, no COMMAND_SET.
+        logger.info(
+            "INTAKE: command_set not minted -- %d/%d items mutative after filter "
+            "(need >= 2 for a batch)",
+            len(command_set_items), len(raw_items),
+        )
+        return None
+
+    # Build a sealed_payload that mirrors bash_validator._build_sealed_payload's
+    # COMMAND_SET shape: command_set verbatim + commands listing every string.
+    # Carry through the subagent's operation/risk fields when present so the
+    # orchestrator's presentation has real values, falling back to neutral
+    # COMMAND_SET defaults otherwise.
+    first_command = command_set_items[0]["command"]
+    sealed_payload = {
+        "operation": approval_req.get("operation")
+        or f"COMMAND_SET intercepted: {len(command_set_items)} commands under one consent",
+        "exact_content": approval_req.get("exact_content") or first_command,
+        "scope": approval_req.get("scope")
+        or (first_command.split()[0] if first_command.strip() else "unknown"),
+        "risk_level": approval_req.get("risk_level") or "medium",
+        "rollback_hint": approval_req.get("rollback") or approval_req.get("rollback_hint"),
+        "rationale": approval_req.get("rationale")
+        or (
+            f"A batch of {len(command_set_items)} related T3 commands requires user "
+            "approval under one consent per the COMMAND_SET policy."
+        ),
+        "commands": [it["command"] for it in command_set_items],
+        "command_set": command_set_items,
+    }
+
+    try:
+        from gaia.approvals.store import insert_requested
+    except ImportError:
+        import pathlib as _pl
+        import sys as _sys
+
+        _repo_root = _pl.Path(__file__).resolve().parent.parent.parent.parent
+        _sys.path.insert(0, str(_repo_root))
+        from gaia.approvals.store import insert_requested
+
+    approval_id = insert_requested(
+        sealed_payload,
+        agent_id=agent_id,
+        session_id=session_id or None,
+    )
+    logger.info(
+        "INTAKE: plan-first COMMAND_SET pending created approval_id=%s items=%d",
+        (approval_id or "")[:16], len(command_set_items),
+    )
+    return approval_id
+
+
 def persist_handoff(
     parsed_contract,
     agent_output: str,
@@ -38,6 +214,38 @@ def persist_handoff(
     import pathlib as _pl
     import sys as _sys
 
+    agent_id = task_info.get("agent_id") or task_info.get("agent") or "unknown"
+
+    # ---------------------------------------------------------------------
+    # INTAKE bridge (plan-first COMMAND_SET) -- run FIRST and INDEPENDENTLY.
+    #
+    # Minting the pending COMMAND_SET approval is the security-critical path:
+    # it is the consent the user must act on. It must not be coupled to the
+    # audit handoff-row write below -- if insert_agent_contract_handoff fails
+    # for any reason, the user must still get the approval to review. So the
+    # intake runs in its own isolated try, before the handoff-row write.
+    #
+    # Only plan-first envelopes act here: command_set >= 2 items AND no
+    # approval_id. A <= 1 item set or a request that already carries an
+    # approval_id (hook-block / singular path) is a no-op for the intake.
+    # ---------------------------------------------------------------------
+    minted_command_set_id = None
+    if parsed_contract is not None:
+        _env = parsed_contract if isinstance(parsed_contract, dict) else {}
+        _approval_req = _env.get("approval_request")
+        if isinstance(_approval_req, dict):
+            try:
+                minted_command_set_id = _intake_command_set_pending(
+                    _approval_req,
+                    agent_id=agent_id,
+                    session_id=session_id,
+                )
+            except Exception as _intake_exc:
+                logger.warning(
+                    "M4: COMMAND_SET intake failed (non-blocking): %s",
+                    _intake_exc,
+                )
+
     try:
         # Prefer a sibling gaia package if installed; fall back to the repo
         # layout where gaia/ lives two levels above hooks/.
@@ -48,7 +256,6 @@ def persist_handoff(
             _sys.path.insert(0, str(_repo_root))
             from gaia.store import writer as _writer
 
-        agent_id = task_info.get("agent_id") or task_info.get("agent") or "unknown"
         workspace = task_info.get("workspace") or _os.environ.get("GAIA_WORKSPACE") or "global"
         db_path_str = task_info.get("db_path")
         db_path = _pl.Path(db_path_str) if db_path_str else None
@@ -99,7 +306,12 @@ def persist_handoff(
             envelope = parsed_contract if isinstance(parsed_contract, dict) else {}
             approval_req = envelope.get("approval_request")
             if approval_req and isinstance(approval_req, dict):
-                approval_id = approval_req.get("approval_id")
+                # The approval_id is either the one the subagent relayed (hook-block
+                # / singular path) or the one the INTAKE bridge just minted for a
+                # plan-first COMMAND_SET. Either way it points at the pending row
+                # the handoff_approvals audit row should link to.
+                approval_id = approval_req.get("approval_id") or minted_command_set_id
+
                 if approval_id:
                     # Look up the grant to determine the decision at stop time.
                     try:

package/hooks/modules/agents/response_contract.py

@@ -402,6 +402,31 @@ def parse_memorialize_suggestions(
     return _extract_memorialize_suggestions(contract)
 
 
+def parse_user_facing_summary(
+    agent_output: str,
+    parsed_contract: Optional[dict] = None,
+) -> Optional[str]:
+    """Parse the optional top-level ``user_facing_summary`` field (Option A).
+
+    This is the ONE human-audience field in the contract: a brief prose summary
+    the subagent writes once, intended for the user. The orchestrator relays it
+    near-verbatim on a single-agent COMPLETE (N=1) instead of re-synthesizing
+    ``key_outputs``; for N>1 it is ignored and synthesis proceeds.
+
+    Strictly additive and advisory: the field is never required and never
+    affects contract validity. Returns the trimmed string when present and
+    non-empty, otherwise None (absent, null, blank, or non-string).
+    """
+    contract = parsed_contract if parsed_contract is not None else parse_contract(agent_output)
+    if contract is None:
+        return None
+    raw = contract.get("user_facing_summary")
+    if not isinstance(raw, str):
+        return None
+    text = raw.strip()
+    return text or None
+
+
 def _is_resume_agent_id(value: str) -> bool:
     return bool(_AGENT_ID_PATTERN.match(value or ""))
 
@@ -659,6 +684,7 @@ __all__ = [
     "parse_evidence_report",
     "parse_consolidation_report",
     "parse_memorialize_suggestions",
+    "parse_user_facing_summary",
     "validate_response_contract",
     "save_validation_result",
     "load_last_validation",

package/hooks/modules/agents/transcript_reader.py

@@ -139,10 +139,25 @@ def extract_injected_context_payload_from_transcript(
     """
     import os
 
+    # Empty/None path guard. Without it, Path("").stem == "" and the substring
+    # match below (``candidate.stem in "" or "" in candidate.stem``) is ALWAYS
+    # True because ``"" in any_string`` is True -- so an empty path would match
+    # (and return) the FIRST payload sitting in gaia-context-payloads/, making
+    # the result depend on whatever happens to be in that directory. Mirror the
+    # guard in read_first_user_content_from_transcript: no path, no match.
+    if not transcript_path:
+        return {}
+
     try:
         payload_dir = Path(os.environ.get("TMPDIR", "/tmp")) / "gaia-context-payloads"
         if payload_dir.exists():
             agent_file = Path(transcript_path).stem  # e.g. "agent-ae190a4da68d626d4"
+            # A stem that came out empty (e.g. path was "/" or "."): nothing to
+            # match against, so the substring test would again degrade to the
+            # always-true ``"" in candidate.stem``. Bail rather than grab an
+            # arbitrary payload.
+            if not agent_file:
+                return {}
             # Match by agent ID substring
             for candidate in payload_dir.glob("*.json"):
                 if candidate.stem in agent_file or agent_file in candidate.stem:

package/hooks/modules/security/__init__.py

@@ -5,7 +5,6 @@ Provides:
 - tiers: SecurityTier enum and classification
 - blocked_commands: Permanently blocked pattern matching
 - mutative_verbs: Mutative verb detection (user approval workflow)
-- gitops_validator: kubectl/helm/flux validation
 - approval_constants: Approval token patterns (legacy APPROVE: and ElicitationResult)
 - approval_grants: Time-limited T3 command passthrough after user approval
 - shell_unwrapper: Detect and strip wrapper shells for inner command classification
@@ -21,7 +20,6 @@ from .blocked_commands import (
     get_blocked_patterns,
     BlockedCommandResult,
 )
-from .gitops_validator import validate_gitops_workflow, GitOpsValidationResult
 from .mutative_verbs import (
     CLI_FAMILY_LOOKUP,
     CATEGORY_MUTATIVE,
@@ -73,9 +71,6 @@ __all__ = [
     "is_blocked_command",
     "get_blocked_patterns",
     "BlockedCommandResult",
-    # GitOps
-    "validate_gitops_workflow",
-    "GitOpsValidationResult",
     # Mutative verbs
     "CLI_FAMILY_LOOKUP",
     "CATEGORY_MUTATIVE",