@jaguilar87/gaia 5.0.6 → 5.0.8

package/dist/gaia-security/hooks/modules/agents/handoff_persister.py

@@ -170,19 +170,30 @@ def _intake_command_set_pending(
     }
 
     try:
-        from gaia.approvals.store import insert_requested
+        from gaia.approvals.store import derive_command_set_id, 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
+        from gaia.approvals.store import derive_command_set_id, insert_requested
+
+    # Derive the PUBLIC approval_id deterministically from the post-filter
+    # mutative command strings. Because the id is content-derived (not uuid4),
+    # the orchestrator reproduces the SAME id from the command_set it reads in
+    # the contract via `gaia approvals derive-id` -- no DB search, no
+    # cross-session miss. The list passed here is the SAME list the CLI helper
+    # derives over (post-mutative-filter), so both sides agree.
+    derived_id = derive_command_set_id(
+        [it["command"] for it in command_set_items]
+    )
 
     approval_id = insert_requested(
         sealed_payload,
         agent_id=agent_id,
         session_id=session_id or None,
+        approval_id=derived_id,
     )
     logger.info(
         "INTAKE: plan-first COMMAND_SET pending created approval_id=%s items=%d",

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

@@ -90,6 +90,11 @@ class BashValidationResult:
     # plain error string (exit 2).  Used for structured block responses that
     # should correct the agent rather than terminate execution.
     block_response: Optional[Dict[str, Any]] = None
+    # When a T3 command is allowed because it matched (and consumed) an active
+    # grant, this carries the approval_id of that grant. The adapter stashes it
+    # in HookState so PostToolUse can append an EXECUTED/FAILED event to the
+    # approval_events chain for this approval. None for non-T3 / no-grant paths.
+    consumed_approval_id: Optional[str] = None
 
     def __post_init__(self):
         if self.suggestions is None:
@@ -667,6 +672,7 @@ class BashValidator:
                     allowed=True,
                     tier=SecurityTier.T3_BLOCKED,
                     reason="Command-set grant matched",
+                    consumed_approval_id=cs_approval_id,
                 )
 
             # DB-primary + filesystem-fallback grant check.
@@ -720,6 +726,7 @@ class BashValidator:
                         allowed=True,
                         tier=SecurityTier.T3_BLOCKED,
                         reason="Grant confirmed",
+                        consumed_approval_id=db_approval_id,
                     )
                 else:
                     # Filesystem grant exists, not yet confirmed -- GAIA approved,
@@ -733,6 +740,7 @@ class BashValidator:
                         allowed=True,
                         tier=SecurityTier.T3_BLOCKED,
                         reason="Grant active, pending confirmation",
+                        consumed_approval_id=db_approval_id,
                     )
             else:
                 # Converge on the single T3 decision point.  When there is an
@@ -808,6 +816,7 @@ class BashValidator:
                             allowed=True,
                             tier=SecurityTier.T3_BLOCKED,
                             reason="Command-set grant matched",
+                            consumed_approval_id=cs_approval_id,
                         )
 
                     grant = check_approval_grant(command, session_id=session_id)
@@ -859,6 +868,7 @@ class BashValidator:
                                 allowed=True,
                                 tier=SecurityTier.T3_BLOCKED,
                                 reason="Grant confirmed",
+                                consumed_approval_id=db_approval_id,
                             )
                         else:
                             logger.info(
@@ -870,6 +880,7 @@ class BashValidator:
                                 allowed=True,
                                 tier=SecurityTier.T3_BLOCKED,
                                 reason="Grant active, pending confirmation",
+                                consumed_approval_id=db_approval_id,
                             )
 
                     # No grant matched -- converge on the single T3 decision
@@ -939,10 +950,18 @@ class BashValidator:
             key=lambda t: tier_order.index(t.value),
         )
 
+        # Propagate the consumed approval_id from whichever component matched a
+        # grant, so PostToolUse can append EXECUTED/FAILED for that approval.
+        consumed_approval_id = next(
+            (r.consumed_approval_id for r in component_results if r.consumed_approval_id),
+            None,
+        )
+
         return BashValidationResult(
             allowed=True,
             tier=highest_tier,
             reason=f"All {len(components)} components validated",
+            consumed_approval_id=consumed_approval_id,
         )
 
     def _phase4_check_composition(

package/gaia/approvals/__init__.py

@@ -6,7 +6,8 @@ Public surface:
     chain.ChainTamperError
     chain.insert_event(con, approval_id, event_type, ...) -> int
 
-    store.insert_requested(sealed_payload, *, agent_id, session_id, con=None) -> str
+    store.insert_requested(sealed_payload, *, agent_id, session_id, approval_id=None, con=None) -> str
+    store.derive_command_set_id(commands) -> str  -- content-derived COMMAND_SET id
     store.record_event(approval_id, event_type, *, ..., con=None) -> int
     store.get_pending(session_id=None, all_sessions=False, con=None) -> list[dict]
     store.list_pending(all_sessions=False, session_id=None, con=None) -> list[dict]

package/gaia/approvals/store.py

@@ -67,16 +67,72 @@ from .chain import (
 
 _APPROVAL_ID_PREFIX = "P-"
 
+# Length (in hex chars) of the content-derived suffix for COMMAND_SET ids.
+# 32 hex chars == 128 bits of the SHA-256 digest, matching the visual length of
+# the uuid4 suffix used by singular approvals (uuid4.hex is also 32 chars).
+_COMMAND_SET_ID_HEX_LEN = 32
+
 
 def _generate_approval_id() -> str:
     """Generate a unique approval ID with the P- prefix.
 
     Format: P-{uuid4_hex}
     Example: P-3f2504e04f8911d39a0c0305e82c3301
+
+    Used for SINGULAR T3 approvals (the hook-block path), where the id only
+    needs to be unique and is relayed verbatim by the subagent. For the
+    plan-first COMMAND_SET path -- where the orchestrator must reproduce the id
+    from the command_set it reads in the contract, with no DB lookup -- use
+    ``derive_command_set_id()`` instead.
     """
     return f"{_APPROVAL_ID_PREFIX}{uuid.uuid4().hex}"
 
 
+def derive_command_set_id(commands: List[str]) -> str:
+    """Deterministically derive a COMMAND_SET approval_id from its command list.
+
+    The plan-first COMMAND_SET id is content-derived rather than random so that
+    BOTH the hook (at SubagentStop intake) and the orchestrator (from the
+    command_set it reads in the contract) compute the SAME id without any DB
+    lookup. This closes the cross-session miss where the orchestrator could not
+    reproduce a uuid4 minted at SubagentStop (Claude Code issue #5812: the
+    SubagentStop output never reaches the parent).
+
+    Format: ``P-<first 32 hex of sha256(canonical([{"command": c}, ...]))>``
+
+    Canonicalization reuses ``chain.canonical_payload`` -- the SAME machinery
+    that produces the fingerprint -- so there is exactly one canonicalization in
+    the system, not a second one. The hash is taken over the ordered list of
+    ``{"command": <str>}`` items, so the id is:
+
+      * **order-sensitive** -- a different command order yields a different id
+        (the consume side matches commands positionally, so order is load-bearing);
+      * **content-only** -- it depends solely on the command strings, not on
+        rationale, session, agent, or timestamp, so the two sides need only the
+        command list (which both have) to agree.
+
+    Idempotency consequence (acceptable, and consistent with the existing
+    fingerprint dedup in ``insert_requested``): two identical command lists map
+    to the same id. No per-attempt salt is added -- both sides could not derive
+    a salt they do not share.
+
+    Args:
+        commands: Ordered list of command strings (the mutative/T3 commands the
+            COMMAND_SET grant will cover). Both the intake and the orchestrator
+            MUST pass the SAME post-filter list for the ids to match.
+
+    Returns:
+        A ``P-{32 hex}`` approval_id deterministically derived from ``commands``.
+    """
+    # Build a minimal, stable structure over the command strings ONLY. We do not
+    # fold in rationale/operation/scope because the orchestrator must reproduce
+    # the id from the command_set alone and those fields may differ between the
+    # subagent's emission and the intake's neutral defaults.
+    canon = canonical_payload({"command_set_commands": list(commands)})
+    digest = hashlib.sha256(canon.encode("utf-8")).hexdigest()
+    return f"{_APPROVAL_ID_PREFIX}{digest[:_COMMAND_SET_ID_HEX_LEN]}"
+
+
 def _now_iso() -> str:
     """Return current UTC time as ISO-8601 (Z suffix)."""
     return datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
@@ -113,12 +169,13 @@ def insert_requested(
     *,
     agent_id: Optional[str] = None,
     session_id: Optional[str] = None,
+    approval_id: Optional[str] = None,
     con: Optional[sqlite3.Connection] = None,
 ) -> str:
     """Insert a new approval row and emit a REQUESTED audit event.
 
     This is the canonical entry point for the T3 hook intercept. It:
-      1. Generates a P-{uuid4} approval_id.
+      1. Generates a P-{uuid4} approval_id (unless one is supplied -- see below).
       2. Computes fingerprint = SHA-256(canonical_json(sealed_payload)).
       3. Inserts a row into approvals with status='pending'.
       4. Calls chain.insert_event() to write REQUESTED to approval_events
@@ -130,14 +187,23 @@ def insert_requested(
             exact_content, scope, risk_level, rollback_hint, rationale, commands).
         agent_id: Optional agent identifier (e.g., agent_id from session context).
         session_id: Optional session identifier (CLAUDE_SESSION_ID).
+        approval_id: Optional caller-supplied approval_id. When provided, it is
+            used as the pending row id instead of minting a fresh P-{uuid4}.
+            This is the plan-first COMMAND_SET path: the intake derives a
+            CONTENT-derived id via ``derive_command_set_id()`` so the
+            orchestrator can reproduce it from the command_set without a DB
+            lookup. The singular T3 hook-block path leaves this None and keeps
+            the uuid4 id. The fingerprint idempotency check below runs FIRST in
+            either case, so a supplied id only takes effect when no pending row
+            with the same fingerprint already exists.
         con: Optional open sqlite3.Connection. When provided, the caller owns
             connection lifecycle (no commit or close). When None, a fresh
             connection to ~/.gaia/gaia.db is opened, committed, and closed.
 
     Returns:
-        The P-{uuid4} approval_id string. When an existing pending approval
-        already carries the same fingerprint, that existing id is returned
-        unchanged (fingerprint idempotency -- see below).
+        The approval_id string used for the pending row. When an existing
+        pending approval already carries the same fingerprint, that existing id
+        is returned unchanged (fingerprint idempotency -- see below).
     """
     # Compute the fingerprint FIRST so we can check for an existing pending with
     # the same byte-binding before minting anything.
@@ -166,10 +232,16 @@ def insert_requested(
         if existing is not None:
             existing_id = existing[0] if not hasattr(existing, "keys") else existing["id"]
             # No INSERT and no REQUESTED event: the chain already holds this
-            # approval's REQUESTED from when it was first minted.
+            # approval's REQUESTED from when it was first minted. Fingerprint
+            # dedup wins over any caller-supplied approval_id: an identical
+            # payload maps to the one pending row that already exists.
             return existing_id
 
-        approval_id = _generate_approval_id()
+        # Use the caller-supplied id (plan-first COMMAND_SET: content-derived,
+        # reproducible by the orchestrator) when given, else mint a uuid4 id
+        # (singular T3 hook-block path).
+        if approval_id is None:
+            approval_id = _generate_approval_id()
 
         # Insert the parent approval row.
         _con.execute(

package/hooks/adapters/claude_code.py

@@ -603,13 +603,18 @@ class ClaudeCodeAdapter(HookAdapter):
                 exit_code=2,
             )
 
-        # Save state for post-hook
+        # Save state for post-hook. When the command was allowed by consuming a
+        # T3 approval grant, carry that approval_id forward so PostToolUse can
+        # append an EXECUTED/FAILED event to the approval_events chain (the grant
+        # is consumed here at PreToolUse and flips to CONSUMED, so PostToolUse
+        # cannot re-discover it via check_approval_grant).
         effective_command = result.modified_input.get("command", command) if result.modified_input else command
         state = create_pre_hook_state(
             tool_name=tool_name,
             command=effective_command,
             tier=str(result.tier),
             allowed=True,
+            consumed_approval_id=result.consumed_approval_id,
         )
         save_hook_state(state)
 
@@ -1003,6 +1008,26 @@ class ClaudeCodeAdapter(HookAdapter):
                             "T3 grant confirmed (will be consumed at SubagentStop): %s", command[:80],
                         )
 
+            # Close the audit-log cycle for an APPROVED T3 command that just ran.
+            # PreToolUse stashed the consumed grant's approval_id in HookState
+            # when it matched (and consumed) the grant; append EXECUTED on a clean
+            # exit, FAILED otherwise. This continues the approval_events hash chain
+            # via the canonical store.record_event() helper -- the only authorized
+            # writer for the chain (it routes through chain.insert_event(), which
+            # links prev_hash -> this_hash before INSERT).
+            if tool_name == "Bash":
+                consumed_approval_id = (
+                    pre_state.metadata.get("consumed_approval_id") if pre_state else None
+                )
+                if consumed_approval_id:
+                    self._record_t3_outcome_event(
+                        consumed_approval_id,
+                        command=parameters.get("command", ""),
+                        success=success,
+                        exit_code=tool_result_data.exit_code,
+                        session_id=hook_data.get("session_id", ""),
+                    )
+
             events = detect_critical_event(tool_name, parameters, output, success)
             if events:
                 writer = SessionContextWriter()
@@ -1031,6 +1056,53 @@ class ClaudeCodeAdapter(HookAdapter):
 
         return HookResponse(output={}, exit_code=0)
 
+    def _record_t3_outcome_event(
+        self,
+        approval_id: str,
+        *,
+        command: str,
+        success: bool,
+        exit_code: int,
+        session_id: str = "",
+    ) -> None:
+        """Append an EXECUTED or FAILED event for an approved T3 command.
+
+        Closes the audit-log cycle: once a command runs under a consumed grant,
+        the approval_events chain records whether it succeeded (EXECUTED) or
+        failed (FAILED). Writes through gaia.approvals.store.record_event(), the
+        canonical chain writer -- never a raw INSERT -- so prev_hash -> this_hash
+        linkage is preserved and validate_chain() stays intact end to end.
+
+        Best-effort and non-fatal: the approval store lives in gaia.db and may be
+        unavailable in some hook contexts; any failure is logged and swallowed so
+        a chain-write hiccup never breaks tool execution.
+        """
+        event_type = "EXECUTED" if success else "FAILED"
+        try:
+            from gaia.approvals import store as _approval_store
+
+            payload = {
+                "command": command,
+                "exit_code": exit_code,
+                "outcome": "success" if success else "failure",
+            }
+            _approval_store.record_event(
+                approval_id,
+                event_type,
+                session_id=session_id or None,
+                payload_json=json.dumps(payload, sort_keys=True, separators=(",", ":")),
+                metadata_json=json.dumps({"source": "post_tool_use"}),
+            )
+            logger.info(
+                "Recorded %s event for approval_id=%s (exit=%d)",
+                event_type, approval_id[:16], exit_code,
+            )
+        except Exception as exc:
+            logger.warning(
+                "Failed to record %s event for approval_id=%s (non-fatal): %s",
+                event_type, approval_id[:16], exc,
+            )
+
     # ------------------------------------------------------------------ #
     # _handle_ask_user_question_result: grant activation from user answer
     # ------------------------------------------------------------------ #

package/hooks/modules/agents/handoff_persister.py

@@ -170,19 +170,30 @@ def _intake_command_set_pending(
     }
 
     try:
-        from gaia.approvals.store import insert_requested
+        from gaia.approvals.store import derive_command_set_id, 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
+        from gaia.approvals.store import derive_command_set_id, insert_requested
+
+    # Derive the PUBLIC approval_id deterministically from the post-filter
+    # mutative command strings. Because the id is content-derived (not uuid4),
+    # the orchestrator reproduces the SAME id from the command_set it reads in
+    # the contract via `gaia approvals derive-id` -- no DB search, no
+    # cross-session miss. The list passed here is the SAME list the CLI helper
+    # derives over (post-mutative-filter), so both sides agree.
+    derived_id = derive_command_set_id(
+        [it["command"] for it in command_set_items]
+    )
 
     approval_id = insert_requested(
         sealed_payload,
         agent_id=agent_id,
         session_id=session_id or None,
+        approval_id=derived_id,
     )
     logger.info(
         "INTAKE: plan-first COMMAND_SET pending created approval_id=%s items=%d",

package/hooks/modules/tools/bash_validator.py

@@ -90,6 +90,11 @@ class BashValidationResult:
     # plain error string (exit 2).  Used for structured block responses that
     # should correct the agent rather than terminate execution.
     block_response: Optional[Dict[str, Any]] = None
+    # When a T3 command is allowed because it matched (and consumed) an active
+    # grant, this carries the approval_id of that grant. The adapter stashes it
+    # in HookState so PostToolUse can append an EXECUTED/FAILED event to the
+    # approval_events chain for this approval. None for non-T3 / no-grant paths.
+    consumed_approval_id: Optional[str] = None
 
     def __post_init__(self):
         if self.suggestions is None:
@@ -667,6 +672,7 @@ class BashValidator:
                     allowed=True,
                     tier=SecurityTier.T3_BLOCKED,
                     reason="Command-set grant matched",
+                    consumed_approval_id=cs_approval_id,
                 )
 
             # DB-primary + filesystem-fallback grant check.
@@ -720,6 +726,7 @@ class BashValidator:
                         allowed=True,
                         tier=SecurityTier.T3_BLOCKED,
                         reason="Grant confirmed",
+                        consumed_approval_id=db_approval_id,
                     )
                 else:
                     # Filesystem grant exists, not yet confirmed -- GAIA approved,
@@ -733,6 +740,7 @@ class BashValidator:
                         allowed=True,
                         tier=SecurityTier.T3_BLOCKED,
                         reason="Grant active, pending confirmation",
+                        consumed_approval_id=db_approval_id,
                     )
             else:
                 # Converge on the single T3 decision point.  When there is an
@@ -808,6 +816,7 @@ class BashValidator:
                             allowed=True,
                             tier=SecurityTier.T3_BLOCKED,
                             reason="Command-set grant matched",
+                            consumed_approval_id=cs_approval_id,
                         )
 
                     grant = check_approval_grant(command, session_id=session_id)
@@ -859,6 +868,7 @@ class BashValidator:
                                 allowed=True,
                                 tier=SecurityTier.T3_BLOCKED,
                                 reason="Grant confirmed",
+                                consumed_approval_id=db_approval_id,
                             )
                         else:
                             logger.info(
@@ -870,6 +880,7 @@ class BashValidator:
                                 allowed=True,
                                 tier=SecurityTier.T3_BLOCKED,
                                 reason="Grant active, pending confirmation",
+                                consumed_approval_id=db_approval_id,
                             )
 
                     # No grant matched -- converge on the single T3 decision
@@ -939,10 +950,18 @@ class BashValidator:
             key=lambda t: tier_order.index(t.value),
         )
 
+        # Propagate the consumed approval_id from whichever component matched a
+        # grant, so PostToolUse can append EXECUTED/FAILED for that approval.
+        consumed_approval_id = next(
+            (r.consumed_approval_id for r in component_results if r.consumed_approval_id),
+            None,
+        )
+
         return BashValidationResult(
             allowed=True,
             tier=highest_tier,
             reason=f"All {len(components)} components validated",
+            consumed_approval_id=consumed_approval_id,
         )
 
     def _phase4_check_composition(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jaguilar87/gaia",
-  "version": "5.0.6",
+  "version": "5.0.8",
   "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.6"
+version = "5.0.8"
 description = "Multi-agent orchestration system for Claude Code - DevOps automation toolkit"
 requires-python = ">=3.11"
 license = {text = "MIT"}

package/skills/agent-approval-protocol/SKILL.md

@@ -21,10 +21,18 @@ the hash chain, grant activation, reading a granted approval from Python -- see
 
 ## approval_id format
 
+For a **singular** T3 approval (the hook-block path),
 `store._generate_approval_id()` returns `P-{uuid4().hex}` (e.g.
-`P-b1bdfbb0b9474bf5b3f86b1f6a213f7a`). The `P-` prefix is mandatory: without it
-the PostToolUse hook cannot do targeted grant activation. The first 8 hex chars
-after `P-` are the nonce prefix shown in option labels: `[P-b1bdfbb0]`.
+`P-b1bdfbb0b9474bf5b3f86b1f6a213f7a`) -- a random, unique id the subagent relays
+verbatim. For a **plan-first `COMMAND_SET`** the id is instead **content-derived**
+by `store.derive_command_set_id()`: `P-<first 32 hex of
+sha256(canonical(command strings))>`. The two share the `P-` prefix and 32-hex
+length but differ in origin -- the command_set id is deterministic so the
+orchestrator reproduces it from the command_set (via `gaia approvals derive-id`)
+with no DB search; the singular id is random because the subagent relays it
+directly. The `P-` prefix is mandatory in both cases: without it the PostToolUse
+hook cannot do targeted grant activation. The first 8 hex chars after `P-` are
+the nonce prefix shown in option labels: `[P-b1bdfbb0]`.
 
 ## APPROVAL_REQUEST contract shape
 
@@ -55,8 +63,11 @@ becomes `rollback` in the contract; `commands` (`[exact_content]`) and
 }
 ```
 
-There is no `batch_scope` field: the `verb_family` grant was removed, so each
-blocked command gets its own single-use grant. See
+There is no `batch_scope` field: the `verb_family` grant was removed. For a
+single blocked command, each gets its own single-use `SCOPE_SEMANTIC_SIGNATURE`
+grant. For a batch of >= 2 T3 commands known up-front, emit a `command_set`
+list and **no** `approval_id` -- the SubagentStop intake mints a single
+`COMMAND_SET` grant (one consent covers all). See
 `Skill('orchestrator-present-approval')` for the orchestrator side.
 
 ## Status vocabularies -- distinct columns, opposite casing, never collapse
@@ -69,8 +80,8 @@ blocked command gets its own single-use grant. See
 ## Event chain
 
 The `approval_events.event_type` CHECK admits nine values: `REQUESTED` `SHOWN`
-`APPROVED` `REJECTED` `EXECUTED` `FAILED` `NOOP` `REVOKED` `REVERTED`. Only these
-are written by production code today:
+`APPROVED` `REJECTED` `EXECUTED` `FAILED` `NOOP` `REVOKED` `REVERTED`. These are
+written by production code today:
 
 | Event | Who writes it | When |
 |-------|--------------|------|
@@ -78,11 +89,16 @@ are written by production code today:
 | `SHOWN` | ElicitationResult hook via `activate_db_pending_by_prefix()` | User selects an Approve `[P-xxx]` label |
 | `APPROVED` | ElicitationResult hook (same call as `SHOWN`) | Immediately after `SHOWN` |
 | `REJECTED` / `REVOKED` | `gaia approvals` CLI via `store.reject()` / `store.revoke()` | User rejects or admin cancels |
-
-`EXECUTED` `FAILED` `NOOP` `REVERTED` are valid in the CHECK and are *read* by
-`store.get_executed_payload()` and `revert.py`, but no production hook *writes*
-them today -- treat them as a designed extension point, not a live invariant. Do
-not assume an `EXECUTED` event exists after a command runs.
+| `EXECUTED` / `FAILED` | PostToolUse adapter (`_record_t3_outcome_event`) via `store.record_event()` | An approved T3 command runs under a consumed grant -- `EXECUTED` on clean exit, `FAILED` otherwise |
+
+The PostToolUse path closes the audit cycle: PreToolUse stashes the consumed
+grant's `approval_id` in `HookState`, and PostToolUse appends `EXECUTED` or
+`FAILED` for that approval, continuing the hash chain through `record_event()`.
+`store.get_executed_payload()` and `gaia approvals replay` read the `EXECUTED`
+payload to re-present the commands that ran. `NOOP` and `REVERTED` remain valid
+in the CHECK but are **inert** -- no production code writes them (the revert
+feature was removed). Do not assume an `EXECUTED` event exists for an approval
+whose command never ran, or that ran through the redirect-sanitized path.
 
 ## Key invariants
 

package/skills/agent-approval-protocol/reference.md

@@ -27,9 +27,11 @@ Each event links to the previous via `prev_hash` -> `this_hash`
 Because `approval_events` is append-only (UPDATE/DELETE blocked by the
 `bu_approval_events_immutable` and `bd_approval_events_immutable` triggers),
 `this_hash` is computed in the application layer before INSERT, inside
-`chain.insert_event()` -- not by a DB trigger. `REVERTED` events, when written,
-carry the original `event_id` in `metadata_json` per the revert design (D14);
-see `gaia/approvals/revert.py`.
+`chain.insert_event()` -- not by a DB trigger. `EXECUTED` / `FAILED` events,
+appended by the PostToolUse adapter through `store.record_event()` after an
+approved T3 command runs, extend the same chain. `REVERTED` remains a valid
+CHECK value but is **inert** -- the revert feature was removed, so no code
+writes it.
 
 ## Grant activation walk-through
 

package/skills/agent-protocol/examples.md

@@ -330,4 +330,15 @@ The agent discovered a project fact a section it owns did not yet hold, and writ
 
 ## Notes on multi-command APPROVAL_REQUEST sweeps
 
-There is no batch/multi-use grant in the current code: the legacy `verb_family` grant was removed (`hooks/modules/security/approval_grants.py`) and its `COMMAND_SET` replacement has no production activation path yet. Do **not** emit a `batch_scope` field -- it is ignored. When one intent expands into many T3 commands, each blocked command produces its own single-use approval; emit one `APPROVAL_REQUEST` per blocked command (shape identical to example 4 above) and let the user approve each.
+**Just-in-time (unknown batch):** when T3 commands appear one at a time as the
+agent works, each blocked command produces its own `APPROVAL_REQUEST` with an
+`approval_id` (shape identical to example 4 above). Do not emit `batch_scope`
+-- it is ignored.
+
+**Plan-first (known batch):** when the agent knows >= 2 T3 commands up-front,
+emit ONE `APPROVAL_REQUEST` carrying a `command_set` list of `{command,
+rationale}` items and **no** `approval_id`. The SubagentStop intake
+(`handoff_persister._intake_command_set_pending`) mints a single `COMMAND_SET`
+approval; the orchestrator presents it as one consent covering all N commands.
+Each command then runs on its own retry, byte-for-byte matched and consumed
+individually.

package/skills/gaia-patterns/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: gaia-patterns
-description: Use when building or modifying gaia-ops components -- agents, skills, hooks, CLI tools, commands, or routing config
+description: Use when building or modifying gaia-ops components -- agents, skills, hooks, CLI tools, or routing config
 metadata:
   user-invocable: false
   type: domain
@@ -77,10 +77,6 @@ Agents get instantiated as: identity (.md) + skills (injected from frontmatter)
 
 CLI tools live in `bin/` and are registered in `package.json` `bin` field. Pattern: parse args, resolve paths (follow symlinks to source), run checks, exit with code. `gaia doctor` is the diagnostic model -- read it first.
 
-## Command Patterns
-
-Slash commands live in `commands/<name>.md` -- markdown files that instruct the orchestrator on `/<name>`. To add: create the `.md`, add to `build/<plugin>.manifest.json`.
-
 ## Documentation Drift Awareness
 
 When you modify any Gaia component (hook, skill, agent definition, routing config, security rule), check if existing reference docs describe that component's behavior. If drift exists, report it via `cross_layer_impacts` in your agent_contract_handoff. The orchestrator then decides whether to dispatch a documentation update task.
@@ -91,7 +87,7 @@ When you modify any Gaia component (hook, skill, agent definition, routing confi
 - Changed `_is_protected()` paths in `adapters/claude_code.py` → check `security-tiers/SKILL.md` for path documentation
 - Added a new agent definition → check `gaia-patterns/reference.md` for agents table
 - Modified hook enforcement logic → check `security-tiers` and `agent-protocol` references
-- When adding or modifying files in agents/, skills/, hooks/, commands/, config/, bin/, tests/, build/ or the repo root, load Skill('readme-writing') to update the relevant README.md
+- When adding or modifying files in agents/, skills/, hooks/, config/, bin/, tests/, build/ or the repo root, load Skill('readme-writing') to update the relevant README.md
 
 **Format:** In `cross_layer_impacts`, list the doc file and the behavior change, e.g.:
 ```