@jaguilar87/gaia 5.0.2 → 5.0.4

package/skills/subagent-request-approval/SKILL.md

@@ -63,12 +63,47 @@ prose are invisible to the presentation -- the user would approve blind.
 - **The grant is single-use.** It is consumed on your first matching retry. A
   second run within the TTL will not match -- it needs a fresh approval.
 
-## Batch / many-command intents
-
-There is **no `batch_scope` field** and no production batch grant: each blocked
-command is one single-use approval, so a sweep of N commands is N approvals.
-The `COMMAND_SET` mechanism exists in code but no path activates it from an
-approval, so emitting `batch_scope` does nothing. See `reference.md` for why.
+## Batch / many-command intents -- COMMAND_SET as a judgment, not a default
+
+Grouping commands under one consent is a **judgment call you earn, not the
+reflex you reach for**. The default is singular, just-in-time approval: attempt
+the command, let the hook block it, request that one. Reach for `COMMAND_SET`
+**only when all three hold** -- the batch is already **known** (the commands are
+determined, not predicted), there are **>= 2** of them, and grouping **actually
+reduces friction** versus approving each as it arrives. If any fails (a single
+command, a sequential flow where the next depends on the last's output, or a
+set you cannot yet name), use the singular path. The principle with its
+consequence: **grouping trades the user's per-command visibility for fewer
+prompts; make that trade only when the batch is real and known, because a batch
+you guessed at asks the user to approve commands that may never run.**
+
+The hard prohibition this rules out: **never invent or predict commands just to
+have something to group.** Speculatively enumerating a `command_set` to "save
+turns" inverts the cost -- it manufactures ceremony (a multi-command consent
+surface) around work that was never determined, which is more overhead than the
+just-in-time blocks it was meant to avoid. If you do not already know the
+commands, you do not have a batch.
+
+When the three conditions do hold, emit an `APPROVAL_REQUEST` whose
+`approval_request` carries a `command_set` -- a list of `{command, rationale}`
+items -- and **no `approval_id`** (nothing has been attempted yet). The
+per-command rationale is what makes the grouped consent honest: the user sees
+why each *known* command is in the batch before approving (D10).
+
+What happens to that envelope: the SubagentStop processor
+(`hooks/modules/agents/handoff_persister.py` -> `_intake_command_set_pending`)
+reads the `command_set`, and when it holds **>= 2** items it calls
+`gaia.approvals.store.insert_requested` with a payload containing the
+`command_set` key. That mints **exactly ONE pending `COMMAND_SET` approval**
+with one `approval_id` -- so a batch of N commands is **one consent, N
+commands**, not N approvals. A set of `<= 1` item is not a batch: it does not
+mint a COMMAND_SET (use the normal singular block path for a single command).
+
+On the user's approval, that one pending activates into a single `COMMAND_SET`
+grant (60-minute TTL); each item is then consumed byte-for-byte on its own
+retry, with replay protection, until the whole set is `CONSUMED`. See
+`reference.md` for the envelope shape, the intake processor, the grant TTL, and
+the consume path.
 
 ## Pointers
 
@@ -84,3 +119,5 @@ approval, so emitting `batch_scope` does nothing. See `reference.md` for why.
 - **Fabricating `approval_id`, fingerprint, or `sealed_payload`** -- the orchestrator validates against the DB; invented values never match.
 - **Reusing a prior approval** -- single-use, consumed on first retry.
 - **Emitting `batch_scope`** -- the field does not exist; it is ignored.
+- **Grouping by reflex** -- reaching for `COMMAND_SET` because a batch *might* form, instead of because a known batch of >= 2 already exists that grouping makes cheaper. The default is singular just-in-time; grouping is the exception you justify.
+- **Predicting commands to fill a batch** -- inventing commands you have not determined so a `command_set` has >= 2 items. You cannot ask consent for work that does not yet exist; the speculative batch is pure overhead.

package/skills/subagent-request-approval/reference.md

@@ -69,35 +69,85 @@ On your retry, `check_approval_grant()` matches it and immediately consumes it
 TTL will NOT match -- the grant is gone. This is replay protection by design;
 re-approve if you need to run the command again.
 
-## Batch / COMMAND_SET -- designed, not wired
+## Batch / COMMAND_SET -- wired
 
 The legacy `verb_family` multi-use grant was removed (see module docstring in
-`approval_grants.py`: "The legacy verb_family path has been removed"). Its intended
+`approval_grants.py`: "The legacy verb_family path has been removed"). Its
 replacement is the `COMMAND_SET` grant -- an explicit list of `{command, rationale}`
 items, each matched byte-for-byte and consumed individually
 (`approval_grants.create_command_set_grant()`; `approval_grants.match_command_set_grant()`).
+All three sides are now wired end-to-end -- **intake**, **activation**, and
+**consume** -- so one consent covers N commands.
+
+**Intake -- plan-first, one pending.** The batch is declared up-front: you emit
+an `APPROVAL_REQUEST` whose `approval_request` carries a `command_set` list and
+**no `approval_id`** (you have attempted nothing). The production intake caller
+is the SubagentStop processor `handoff_persister.persist_handoff()`, which calls
+`_intake_command_set_pending()`. That helper normalizes the `command_set` and,
+when it holds **>= 2** `{command, rationale}` items, builds a sealed_payload
+carrying the `command_set` key (mirroring the shape
+`bash_validator._build_sealed_payload()` emits) and calls
+`gaia.approvals.store.insert_requested()` -- minting **exactly ONE** pending
+`COMMAND_SET` approval with one `approval_id`. A set of length `<= 1` is not a
+batch: the intake declines and the singular semantic-signature path owns it (no
+COMMAND_SET is ever minted for one command). The intake runs independently of
+the audit handoff-row write, so a batch consent is never lost to an unrelated
+DB failure.
+
+**Envelope shape.** The sealed_payload the intake writes carries a `command_set`
+key holding the verbatim list of `{command, rationale}` items, and `commands`
+listing every command string in the set:
 
-**Current state:** only the CHECK side is wired. `bash_validator._validate_single_command()`
-calls `match_command_set_grant()` and consumes a matched item, but **no
-production path calls `approval_grants.create_command_set_grant()`** -- it exists only in the
-module and its tests. The activation paths only call
-`approval_grants.activate_db_pending_by_prefix()`, which creates a single-use
-`SCOPE_SEMANTIC_SIGNATURE` grant.
+```json
+{
+  "operation": "MUTATIVE command intercepted: push",
+  "exact_content": "git add -A",
+  "commands": ["git add -A", "git commit -m 'v1.2.0'", "git push origin main"],
+  "command_set": [
+    {"command": "git add -A",             "rationale": "stage release files"},
+    {"command": "git commit -m 'v1.2.0'", "rationale": "record the release commit"},
+    {"command": "git push origin main",   "rationale": "publish to the remote"}
+  ]
+}
+```
 
-**Consequence:** a `batch_scope` field in `approval_request`, or the word "batch"
-in a label, 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.
+**Activation -- one consent, one grant.** When the user approves, the
+ElicitationResult hook (`approval_grants.activate_db_pending_by_prefix()`)
+detects the `command_set` and branches to `approval_grants.create_command_set_grant()`,
+which inserts a single `COMMAND_SET` grant row into `approval_grants`
+(status `PENDING`, `command_set_json` holding the whole set). The grant TTL is
+**60 minutes** (`DEFAULT_COMMAND_SET_TTL_MINUTES`), aligned to the singular
+active-grant TTL so the batch does not expire mid-consume across sessions.
+
+**Consume -- item by item, replay-protected.** On each retry,
+`bash_validator._validate_single_command()` calls `match_command_set_grant()`,
+which finds the matching command's index byte-for-byte and returns it; the
+validator then calls `mark_command_set_item_consumed()`, appending that index to
+`consumed_indexes_json`. A consumed index never matches again (replay
+protection), and when every index is consumed the grant flips to `CONSUMED`.
+Wrapping an approved command -- adding `cd`, a redirect, a pipe, or a flag --
+produces a different string and matches nothing in the set; it requires fresh
+approval.
+
+**Consequence:** for a set of N related T3 commands, emit the `command_set`
+envelope and the user approves once. Each command runs on its own retry,
+single-use within the 60-minute window.
 
 ## Status to emit -- with vs without approval_id
 
 Always `plan_status: "APPROVAL_REQUEST"`. The presence of `approval_id` tells the
 orchestrator which path:
 
-- **With `approval_id`** -- the hook blocked; orchestrator validates the
-  fingerprint and activates the grant on user approval.
-- **Without `approval_id`** -- plan-first (you are presenting a T3 plan before
-  attempting); the orchestrator gates on user consent before any execution.
+- **With `approval_id`** -- the hook blocked a single command; orchestrator
+  validates the fingerprint and activates the single-use semantic grant on user
+  approval.
+- **Without `approval_id`, with a `command_set` of >= 2 items** -- plan-first
+  batch. The SubagentStop intake processor mints ONE pending `COMMAND_SET` and
+  the orchestrator presents that single approval (N commands, one nonce) before
+  any execution. See "Batch / COMMAND_SET -- wired" above.
+- **Without `approval_id` and without a multi-item `command_set`** -- plan-first
+  single (you are presenting one T3 plan before attempting); the orchestrator
+  gates on user consent before any execution.
 
 ## Examples
 

package/tools/context/README.md

@@ -77,7 +77,7 @@ Agent contracts live in `~/.gaia/gaia.db` (`project_context_contracts` + `agent_
 **cloud-troubleshooter:**
 - project_identity, stack, git, environment, infrastructure, orchestration
 - cluster_details, infrastructure_topology, terraform_infrastructure
-- gitops_configuration, application_services, monitoring_observability, architecture_overview
+- gitops_configuration, application_services, architecture_overview
 
 The same contracts are exposed under `write_permissions`:
 - `readable_sections`

package/tools/gaia_simulator/extractor.py

@@ -221,7 +221,6 @@ class LogExtractor:
                 # Exit 2 BLOCK (block_response is None):
                 #   - "Command blocked by security policy ..." -- permanent deny list
                 #   - "Commit message validation failed ..." -- validation error
-                #   - "GitOps policy violation ..." -- GitOps validation
                 #   - "Empty command not allowed"
                 if (
                     reason.startswith("Dangerous")

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

@@ -1,179 +0,0 @@
-"""
-GitOps workflow validation for kubectl, helm, and flux commands.
-
-Ensures commands follow GitOps principles:
-- No direct cluster modifications
-- Use --dry-run for apply operations
-- Prefer read-only commands
-"""
-
-import re
-import logging
-from typing import List, Optional
-from dataclasses import dataclass, field
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class GitOpsValidationResult:
-    """Result of GitOps validation."""
-    allowed: bool
-    reason: str
-    severity: str = "info"  # info, warning, high, critical
-    suggestions: List[str] = field(default_factory=list)
-
-
-# Safe read-only commands (always allowed)
-SAFE_KUBECTL_COMMANDS = [
-    r'kubectl\s+get',
-    r'kubectl\s+describe',
-    r'kubectl\s+logs',
-    r'kubectl\s+top',
-    r'kubectl\s+explain',
-    r'kubectl\s+version',
-    r'kubectl\s+cluster-info',
-    r'kubectl\s+config\s+view',
-    r'kubectl\s+api-resources',
-    r'kubectl\s+api-versions',
-]
-
-SAFE_FLUX_COMMANDS = [
-    r'flux\s+get',
-    r'flux\s+check',
-    r'flux\s+version',
-    r'flux\s+logs',
-    r'flux\s+stats',
-    r'flux\s+tree',
-]
-
-SAFE_HELM_COMMANDS = [
-    r'helm\s+list',
-    r'helm\s+status',
-    r'helm\s+history',
-    r'helm\s+template',
-    r'helm\s+lint',
-    r'helm\s+version',
-    r'helm\s+show',
-    r'helm\s+search',
-]
-
-# Forbidden commands (modify cluster state)
-FORBIDDEN_KUBECTL_COMMANDS = [
-    r'kubectl\s+apply(?!\s+.*--dry-run)',
-    r'kubectl\s+create(?!\s+.*--dry-run)',
-    r'kubectl\s+patch',
-    r'kubectl\s+replace',
-    r'kubectl\s+delete',
-    r'kubectl\s+scale',
-    r'kubectl\s+rollout\s+restart',
-    r'kubectl\s+annotate(?!\s+.*--dry-run)',
-    r'kubectl\s+label(?!\s+.*--dry-run)',
-]
-
-FORBIDDEN_FLUX_COMMANDS = [
-    r'flux\s+create',
-    r'flux\s+delete',
-    r'flux\s+suspend',
-    r'flux\s+resume',
-]
-
-FORBIDDEN_HELM_COMMANDS = [
-    r'helm\s+install(?!\s+.*--dry-run)',
-    r'helm\s+upgrade(?!\s+.*--dry-run)',
-    r'helm\s+uninstall',
-    r'helm\s+rollback',
-]
-
-
-def is_safe_gitops_command(command: str) -> bool:
-    """Check if command is explicitly safe (read-only)."""
-    safe_patterns = SAFE_KUBECTL_COMMANDS + SAFE_FLUX_COMMANDS + SAFE_HELM_COMMANDS
-    for pattern in safe_patterns:
-        if re.search(pattern, command, re.IGNORECASE):
-            return True
-    return False
-
-
-def is_forbidden_gitops_command(command: str) -> bool:
-    """Check if command is forbidden (modifies cluster state)."""
-    forbidden_patterns = (
-        FORBIDDEN_KUBECTL_COMMANDS +
-        FORBIDDEN_FLUX_COMMANDS +
-        FORBIDDEN_HELM_COMMANDS
-    )
-    for pattern in forbidden_patterns:
-        if re.search(pattern, command, re.IGNORECASE):
-            return True
-    return False
-
-
-def validate_gitops_workflow(
-    command: str,
-    agent_type: Optional[str] = None
-) -> GitOpsValidationResult:
-    """
-    Validate command against GitOps security principles.
-
-    Args:
-        command: Shell command to validate
-        agent_type: Optional agent type for stricter validation
-
-    Returns:
-        GitOpsValidationResult with status and suggestions
-    """
-    # Check if command is explicitly safe
-    if is_safe_gitops_command(command):
-        return GitOpsValidationResult(
-            allowed=True,
-            reason="Read-only operation - safe to execute",
-        )
-
-    # Check if command is forbidden
-    if is_forbidden_gitops_command(command):
-        suggestions = []
-
-        # Provide specific suggestions based on command type
-        if "kubectl apply" in command and "--dry-run" not in command:
-            suggestions.extend([
-                "Use: kubectl apply --dry-run=client -f <file>",
-                "Create manifests in gitops repository first",
-                "Commit changes and let Flux CD reconcile"
-            ])
-        elif "flux reconcile" in command and "--dry-run" not in command:
-            suggestions.extend([
-                "Use: flux reconcile <resource> --dry-run",
-                "Follow GitOps workflow: commit -> push -> automatic reconciliation"
-            ])
-        elif "helm install" in command or "helm upgrade" in command:
-            suggestions.extend([
-                "Use: helm template or helm upgrade --dry-run",
-                "Deploy via HelmRelease manifests in gitops repository"
-            ])
-        else:
-            suggestions.append("Use read-only commands or --dry-run alternatives")
-
-        return GitOpsValidationResult(
-            allowed=False,
-            reason="Command violates GitOps principles - modifies cluster state directly",
-            severity="critical",
-            suggestions=suggestions,
-        )
-
-    # For gitops-operator agent, be extra strict
-    if agent_type == "gitops-operator":
-        if ("apply" in command or "create" in command) and "--dry-run" not in command:
-            return GitOpsValidationResult(
-                allowed=False,
-                reason="GitOps operator must use --dry-run for all apply operations",
-                severity="high",
-                suggestions=["Add --dry-run=client flag to command"],
-            )
-
-    # Default: allow but warn about unclear intent
-    return GitOpsValidationResult(
-        allowed=True,
-        reason="Command not explicitly validated - proceed with caution",
-        severity="warning",
-        suggestions=["Verify command follows GitOps principles"],
-    )

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

@@ -1,179 +0,0 @@
-"""
-GitOps workflow validation for kubectl, helm, and flux commands.
-
-Ensures commands follow GitOps principles:
-- No direct cluster modifications
-- Use --dry-run for apply operations
-- Prefer read-only commands
-"""
-
-import re
-import logging
-from typing import List, Optional
-from dataclasses import dataclass, field
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class GitOpsValidationResult:
-    """Result of GitOps validation."""
-    allowed: bool
-    reason: str
-    severity: str = "info"  # info, warning, high, critical
-    suggestions: List[str] = field(default_factory=list)
-
-
-# Safe read-only commands (always allowed)
-SAFE_KUBECTL_COMMANDS = [
-    r'kubectl\s+get',
-    r'kubectl\s+describe',
-    r'kubectl\s+logs',
-    r'kubectl\s+top',
-    r'kubectl\s+explain',
-    r'kubectl\s+version',
-    r'kubectl\s+cluster-info',
-    r'kubectl\s+config\s+view',
-    r'kubectl\s+api-resources',
-    r'kubectl\s+api-versions',
-]
-
-SAFE_FLUX_COMMANDS = [
-    r'flux\s+get',
-    r'flux\s+check',
-    r'flux\s+version',
-    r'flux\s+logs',
-    r'flux\s+stats',
-    r'flux\s+tree',
-]
-
-SAFE_HELM_COMMANDS = [
-    r'helm\s+list',
-    r'helm\s+status',
-    r'helm\s+history',
-    r'helm\s+template',
-    r'helm\s+lint',
-    r'helm\s+version',
-    r'helm\s+show',
-    r'helm\s+search',
-]
-
-# Forbidden commands (modify cluster state)
-FORBIDDEN_KUBECTL_COMMANDS = [
-    r'kubectl\s+apply(?!\s+.*--dry-run)',
-    r'kubectl\s+create(?!\s+.*--dry-run)',
-    r'kubectl\s+patch',
-    r'kubectl\s+replace',
-    r'kubectl\s+delete',
-    r'kubectl\s+scale',
-    r'kubectl\s+rollout\s+restart',
-    r'kubectl\s+annotate(?!\s+.*--dry-run)',
-    r'kubectl\s+label(?!\s+.*--dry-run)',
-]
-
-FORBIDDEN_FLUX_COMMANDS = [
-    r'flux\s+create',
-    r'flux\s+delete',
-    r'flux\s+suspend',
-    r'flux\s+resume',
-]
-
-FORBIDDEN_HELM_COMMANDS = [
-    r'helm\s+install(?!\s+.*--dry-run)',
-    r'helm\s+upgrade(?!\s+.*--dry-run)',
-    r'helm\s+uninstall',
-    r'helm\s+rollback',
-]
-
-
-def is_safe_gitops_command(command: str) -> bool:
-    """Check if command is explicitly safe (read-only)."""
-    safe_patterns = SAFE_KUBECTL_COMMANDS + SAFE_FLUX_COMMANDS + SAFE_HELM_COMMANDS
-    for pattern in safe_patterns:
-        if re.search(pattern, command, re.IGNORECASE):
-            return True
-    return False
-
-
-def is_forbidden_gitops_command(command: str) -> bool:
-    """Check if command is forbidden (modifies cluster state)."""
-    forbidden_patterns = (
-        FORBIDDEN_KUBECTL_COMMANDS +
-        FORBIDDEN_FLUX_COMMANDS +
-        FORBIDDEN_HELM_COMMANDS
-    )
-    for pattern in forbidden_patterns:
-        if re.search(pattern, command, re.IGNORECASE):
-            return True
-    return False
-
-
-def validate_gitops_workflow(
-    command: str,
-    agent_type: Optional[str] = None
-) -> GitOpsValidationResult:
-    """
-    Validate command against GitOps security principles.
-
-    Args:
-        command: Shell command to validate
-        agent_type: Optional agent type for stricter validation
-
-    Returns:
-        GitOpsValidationResult with status and suggestions
-    """
-    # Check if command is explicitly safe
-    if is_safe_gitops_command(command):
-        return GitOpsValidationResult(
-            allowed=True,
-            reason="Read-only operation - safe to execute",
-        )
-
-    # Check if command is forbidden
-    if is_forbidden_gitops_command(command):
-        suggestions = []
-
-        # Provide specific suggestions based on command type
-        if "kubectl apply" in command and "--dry-run" not in command:
-            suggestions.extend([
-                "Use: kubectl apply --dry-run=client -f <file>",
-                "Create manifests in gitops repository first",
-                "Commit changes and let Flux CD reconcile"
-            ])
-        elif "flux reconcile" in command and "--dry-run" not in command:
-            suggestions.extend([
-                "Use: flux reconcile <resource> --dry-run",
-                "Follow GitOps workflow: commit -> push -> automatic reconciliation"
-            ])
-        elif "helm install" in command or "helm upgrade" in command:
-            suggestions.extend([
-                "Use: helm template or helm upgrade --dry-run",
-                "Deploy via HelmRelease manifests in gitops repository"
-            ])
-        else:
-            suggestions.append("Use read-only commands or --dry-run alternatives")
-
-        return GitOpsValidationResult(
-            allowed=False,
-            reason="Command violates GitOps principles - modifies cluster state directly",
-            severity="critical",
-            suggestions=suggestions,
-        )
-
-    # For gitops-operator agent, be extra strict
-    if agent_type == "gitops-operator":
-        if ("apply" in command or "create" in command) and "--dry-run" not in command:
-            return GitOpsValidationResult(
-                allowed=False,
-                reason="GitOps operator must use --dry-run for all apply operations",
-                severity="high",
-                suggestions=["Add --dry-run=client flag to command"],
-            )
-
-    # Default: allow but warn about unclear intent
-    return GitOpsValidationResult(
-        allowed=True,
-        reason="Command not explicitly validated - proceed with caution",
-        severity="warning",
-        suggestions=["Verify command follows GitOps principles"],
-    )