@jaguilar87/gaia 5.0.7 → 5.0.9

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/hooks/post_compact.py

@@ -35,6 +35,7 @@ def _handle_post_compact(event) -> None:
 
     response = {
         "hookSpecificOutput": {
+            "hookEventName": "PostCompact",
             "additionalContext": context,
         }
     }

package/hooks/pre_compact.py

@@ -52,6 +52,7 @@ def _handle_pre_compact(event) -> None:
 
     response = {
         "hookSpecificOutput": {
+            "hookEventName": "PreCompact",
             "additionalContext": context,
         }
     }

package/hooks/user_prompt_submit.py

@@ -194,6 +194,26 @@ if __name__ == "__main__":
             else:
                 logger.info("Could not extract user prompt from stdin, skipping routing")
 
+            # Per-turn VERIFIED pending approvals. Lets the orchestrator present
+            # a pending approval for consent directly from injected context,
+            # WITHOUT dispatching a subagent to derive/verify it (that dispatch's
+            # SubagentStop caused a pending-revocation bug). Emits "" when there
+            # are no verified pendings, so a turn with nothing pending injects
+            # nothing -- this is what keeps the per-turn injection quiet, unlike
+            # the one-shot SessionStart summary it deliberately does not re-emit.
+            try:
+                from modules.session.session_manifest import (
+                    build_per_turn_pending_approvals_block,
+                )
+                pending_block = build_per_turn_pending_approvals_block()
+                if pending_block:
+                    context_parts.append(pending_block)
+            except Exception as _pa_exc:
+                logger.debug(
+                    "per-turn pending approvals injection failed (non-fatal): %s",
+                    _pa_exc,
+                )
+
         additional_context = "\n\n".join(context_parts)
         logger.info("Context injected: %s mode (%d chars)", mode, len(additional_context))
 

package/package.json

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

package/scripts/bootstrap_database.sh

@@ -211,9 +211,13 @@ fi
 #     EXPECTED_SCHEMA_VERSION en doctor.py en el mismo commit.
 #   - Para una DB en el FLOOR, esa migración corre directo (la DB está en el
 #     estado source de la migración). No se necesitan variantes _fresh: un
-#     fresh install ya está en EXPECTED tras schema.sql, así que el loop no
-#     entra (CURRENT == EXPECTED). El guard-probe por-versión del modelo viejo
-#     desaparece junto con la cadena histórica.
+#     fresh install sella el ledger en el FLOOR (Section 3b) y, cuando hay
+#     migraciones forward (EXPECTED > FLOOR), ESTE loop SÍ se replaya en cada
+#     fresh install desde FLOOR+1 hasta EXPECTED contra una DB cuyos objetos
+#     schema.sql ya creó -- por eso las migraciones DEBEN ser idempotentes
+#     (CREATE ... IF NOT EXISTS; ADD COLUMN neutralizado por el guard runner).
+#     El guard-probe por-versión del modelo viejo desaparece junto con la
+#     cadena histórica.
 #
 # Cada migración corre en su propia transacción BEGIN/COMMIT. Si falla, abort
 # -- el ledger NO avanza y el próximo bootstrap retry ve la misma pendiente.
@@ -245,13 +249,58 @@ echo "[bootstrap] schema_version: current=${CURRENT_VERSION}, expected=${EXPECTE
 
 MIG_DIR="${SCRIPT_DIR}/migrations"
 
+# --- Idempotent ADD COLUMN guard (runner-level) ------------------------------
+#
+# Forward migrations are applied on EVERY fresh install: schema.sql produces the
+# EXPECTED shape, the ledger is stamped at the FLOOR, and Section 3c walks
+# FLOOR+1..EXPECTED (this is what test_fresh_install_stamps_floor and
+# test_bootstrap_idempotent_at_floor require). Because schema.sql already
+# carries each migration's target DDL (see migrations/README.md section 1:
+# "add the DDL to schema.sql AND create the migration"), a migration is always
+# replayed against a DB that already has its objects.
+#
+# CREATE ... IF NOT EXISTS makes CREATE statements idempotent under that replay
+# (v18_to_v19 relies on it). But SQLite has NO `ADD COLUMN IF NOT EXISTS`, so a
+# bare `ALTER TABLE t ADD COLUMN c` aborts with "duplicate column name" when the
+# column already exists from schema.sql. This guard restores idempotency for
+# ADD COLUMN at the RUNNER level (not by putting invalid SQL in the .sql file):
+# for each `ALTER TABLE <t> ADD COLUMN <c> ...` line, if column <c> already
+# exists on table <t> (PRAGMA table_info), the line is neutralised (commented
+# out) before the migration runs. Every other statement passes through verbatim.
+#
+# Pure bash + sqlite3, no python3 -- consistent with this script's principles.
+_filter_add_column_idempotent() {
+    # $1 = path to the migration .sql file. Emits the (possibly filtered) SQL on
+    # stdout. Lines that are `ALTER TABLE t ADD COLUMN c` for an existing column
+    # are replaced by a comment; all other lines are passed through unchanged.
+    local mig_file="$1"
+    local line lower table col exists
+    while IFS= read -r line || [ -n "$line" ]; do
+        # Normalise whitespace for matching only (emit the ORIGINAL line).
+        lower="$(printf '%s' "$line" | tr '[:upper:]' '[:lower:]')"
+        if [[ "$lower" =~ alter[[:space:]]+table[[:space:]]+([a-z0-9_]+)[[:space:]]+add[[:space:]]+column[[:space:]]+([a-z0-9_]+) ]]; then
+            table="${BASH_REMATCH[1]}"
+            col="${BASH_REMATCH[2]}"
+            exists="$(sqlite3 "$GAIA_DB" "SELECT COUNT(*) FROM pragma_table_info('${table}') WHERE name='${col}';")"
+            if [ "$exists" -gt 0 ]; then
+                printf -- '-- [bootstrap] skipped (column %s.%s already present): %s\n' "$table" "$col" "$line"
+                continue
+            fi
+        fi
+        printf '%s\n' "$line"
+    done < "$mig_file"
+}
+
 if [ "$CURRENT_VERSION" -lt "$EXPECTED_VERSION" ]; then
-    # Forward-only loop. Reaches here only when a FUTURE migration has been
-    # added (EXPECTED_SCHEMA_VERSION > FLOOR) and the live DB is behind it.
-    # On a fresh install the DB is already at EXPECTED (schema.sql produced the
-    # FLOOR == EXPECTED shape when no forward migrations exist), so this branch
-    # is skipped entirely. Any DB below the FLOOR was already rejected in
-    # Section 3b, so CURRENT_VERSION here is always >= FLOOR.
+    # Forward-only loop. Runs whenever the live DB is behind EXPECTED, which
+    # INCLUDES a fresh install: Section 3b stamps the ledger at the FLOOR, and
+    # when forward migrations exist (EXPECTED > FLOOR) a fresh DB sits at the
+    # FLOOR while EXPECTED is higher, so it enters here and replays FLOOR+1..
+    # EXPECTED. That replay runs against a DB whose objects schema.sql already
+    # created, which is exactly why these migrations MUST be idempotent (CREATE
+    # ... IF NOT EXISTS; ADD COLUMN neutralised by the runner guard above).
+    # Any DB below the FLOOR was already rejected in Section 3b, so
+    # CURRENT_VERSION here is always >= FLOOR.
     for N in $(seq $((CURRENT_VERSION + 1)) "$EXPECTED_VERSION"); do
         PREV=$((N - 1))
         MIG_FILE="${MIG_DIR}/v${PREV}_to_v${N}.sql"
@@ -263,15 +312,15 @@ if [ "$CURRENT_VERSION" -lt "$EXPECTED_VERSION" ]; then
             exit 1
         fi
 
-        # Forward-only: a DB at the FLOOR (or any version below N) is in the
-        # source state of this migration, so we apply it directly inside an
-        # explicit transaction. No per-version guard probe and no _fresh
-        # variant are needed -- the historical "schema.sql already created the
-        # target table" case only existed because the baseline was v1 and the
-        # whole chain was walked on every fresh install. Under the FLOOR model
-        # a fresh install is already at EXPECTED, so it never enters this loop.
+        # Apply the migration inside an explicit transaction. The SQL is passed
+        # through _filter_add_column_idempotent first so that `ADD COLUMN`
+        # statements for columns schema.sql already created are skipped (SQLite
+        # lacks `ADD COLUMN IF NOT EXISTS`). CREATE ... IF NOT EXISTS statements
+        # are already idempotent and pass through unchanged. This is what lets a
+        # fresh install (where schema.sql produced the EXPECTED shape) replay the
+        # FLOOR+1..EXPECTED migrations without aborting on duplicate columns.
         echo "[bootstrap] migration v${PREV}->v${N}: applying ${MIG_FILE}"
-        MIG_SQL="$(cat "$MIG_FILE")"
+        MIG_SQL="$(_filter_add_column_idempotent "$MIG_FILE")"
         if ! sqlite3 "$GAIA_DB" <<EOF
 BEGIN;
 ${MIG_SQL}

package/scripts/migrations/README.md

@@ -17,25 +17,31 @@ The floor is **v18**. It is declared in three places that must agree:
 
 | Location | What it holds |
 |----------|---------------|
-| `gaia/store/schema.sql` | Produces the v18 shape directly (fresh installs land here). |
-| `scripts/bootstrap_database.sh` Section 3b (`SCHEMA_FLOOR=18`) | Seeds/stamps the ledger at the floor; rejects DBs below it. |
-| `bin/cli/doctor.py` (`EXPECTED_SCHEMA_VERSION`) | The version the CLI expects; equals the floor until a forward migration is added. |
+| `gaia/store/schema.sql` | Produces the **latest** (EXPECTED) shape directly -- fresh installs land here, not at the floor. |
+| `scripts/bootstrap_database.sh` Section 3b (`SCHEMA_FLOOR=18`) | Stamps the fresh ledger at the floor; rejects DBs below it. |
+| `bin/cli/doctor.py` (`EXPECTED_SCHEMA_VERSION`) | The version the CLI expects; equals the floor when no forward migration exists, and the highest migration target once they do. |
 
 How bootstrap treats each case:
 
 * **Fresh install** (no `schema_version` rows): `schema.sql` already produced
-  the floor shape, so bootstrap stamps `(version=18, ...)` directly. It does
-  **not** seed v1 and walk the chain.
-* **DB at or above the floor** (the common case, e.g. `~/.gaia/gaia.db`): no
-  migration needed. Section 3c only runs if a forward migration exists.
+  the EXPECTED shape, and Section 3b stamps the ledger at the **floor** (not
+  EXPECTED). Section 3c then replays every forward migration from `floor+1` to
+  EXPECTED against that already-current DB. It does **not** seed v1 and walk the
+  historical chain. Because the migrations run against objects `schema.sql`
+  already created, they **must be idempotent** (see section 1).
+* **DB at or above the floor** (the common case, e.g. `~/.gaia/gaia.db`):
+  Section 3c applies any forward migrations the DB is still behind on, up to
+  EXPECTED.
 * **DB below the floor** (`1 <= version < 18`): **no longer supported** for
   in-place upgrade. Bootstrap aborts with a clear message asking you to
   recreate the DB (back up, delete `~/.gaia/gaia.db`, re-run `gaia install`).
 
 There are no `_fresh` / `_merge` variants under the floor model. Those existed
 only because the old baseline was v1 and the whole chain was walked on every
-fresh install. With the floor, a fresh install is already at the expected
-version after `schema.sql`, so the migration loop is skipped entirely.
+fresh install. Under the floor model the forward-migration loop is still
+replayed on every fresh install (from `floor+1` to EXPECTED) -- so the single
+forward migration file per bump must be idempotent rather than split into
+`_fresh` / `_merge` variants.
 
 ---
 
@@ -48,14 +54,19 @@ version) to `N`:
 1. Add the new DDL to `gaia/store/schema.sql` so fresh installs land in the
    target shape.
 2. Create exactly one `scripts/migrations/v{N-1}_to_v{N}.sql` containing the
-   full DDL delta applied to a DB at version `N-1`.
+   full DDL delta applied to a DB at version `N-1`. It **must be idempotent**
+   (`CREATE ... IF NOT EXISTS`; for `ADD COLUMN`, rely on the runner's
+   existence guard -- SQLite has no `ADD COLUMN IF NOT EXISTS`), because it is
+   replayed on fresh installs against a DB that already has those objects.
 3. Bump `EXPECTED_SCHEMA_VERSION` to `N` in `bin/cli/doctor.py` **in the same
    commit**.
 
 `bootstrap_database.sh` Section 3c then applies `v{N-1}_to_v{N}.sql` inside a
 single `BEGIN/COMMIT` transaction for any DB behind `N`, and stamps the ledger
-only on success. A fresh install is already at `N` after `schema.sql`, so it
-never enters the loop -- no `_fresh` variant is required.
+only on success. A fresh install stamps the ledger at the floor (Section 3b)
+and then replays `floor+1 .. N` here too -- since `schema.sql` already produced
+the `N` shape, the migration runs against objects that already exist, which is
+exactly why it must be idempotent (no `_fresh` variant is used).
 
 `tests/cli/test_schema_version_lockstep.py` enforces that
 `EXPECTED_SCHEMA_VERSION` equals the floor when no forward migrations exist,
@@ -93,8 +104,9 @@ as the ledger grows.
 | `vN_to_vN+1.sql` | Applied to an existing DB at version N. Contains the full DDL delta, applied inside a `BEGIN/COMMIT` transaction by bootstrap Section 3c. |
 
 The historical `_fresh` and `_merge` variants are no longer used: under the
-floor model a fresh install is already at the expected version after
-`schema.sql`, so it never runs a migration script.
+floor model a single idempotent `vN_to_vN+1.sql` covers both an in-place
+upgrade and the fresh-install replay (Section 3c walks `floor+1 .. EXPECTED`
+on every fresh install), so one idempotent file replaces the old split.
 
 ---
 

package/scripts/migrations/schema.checksum

@@ -4,5 +4,5 @@
 # corresponds to (EXPECTED_SCHEMA_VERSION in bin/cli/doctor.py).
 # Do NOT edit by hand: bump EXPECTED_SCHEMA_VERSION + add a migration,
 # then re-run the guard to refresh this file.
-version=18
-sha256=6f728de0625d5011b86eaf536c21785d19cfa08592ecaf086ab46f9b0d0ebda0
+version=20
+sha256=027c8a61e8217b40cbdb07d0b83e7fb18f1ec671d3069dc0a0ce6bb4cc0e8ee9

package/scripts/migrations/v18_to_v19.sql

@@ -0,0 +1,36 @@
+-- Migration v18 -> v19: audit-immutability gap closure (Task B).
+--
+-- Adds BEFORE UPDATE trigger bu_approvals_status_has_event on the approvals
+-- table to enforce that every approvals.status transition is accompanied by a
+-- preceding event row in the append-only approval_events chain.
+--
+-- The trigger fires when status changes to 'approved', 'rejected', or 'revoked'.
+-- It checks that an event row with the matching event_type exists for the
+-- approval_id within the same transaction. If no matching event is found it
+-- raises ABORT, rolling back the UPDATE.
+--
+-- This closes the gap where a direct UPDATE approvals SET status = 'approved'
+-- could flip the status column without leaving an auditable event, violating
+-- the "auditable + immutable" invariant of the approval_events chain.
+--
+-- Bootstrap note: a fresh install (schema.sql) already includes this trigger
+-- via CREATE TRIGGER IF NOT EXISTS; this migration only adds it to existing DBs
+-- that were initialized before v19.
+
+CREATE TRIGGER IF NOT EXISTS bu_approvals_status_has_event
+BEFORE UPDATE OF status ON approvals
+WHEN NEW.status != OLD.status AND NEW.status IN ('approved', 'rejected', 'revoked')
+BEGIN
+    SELECT CASE
+        WHEN (
+            SELECT COUNT(*) FROM approval_events
+             WHERE approval_id = NEW.id
+               AND event_type = CASE NEW.status
+                                    WHEN 'approved' THEN 'APPROVED'
+                                    WHEN 'rejected' THEN 'REJECTED'
+                                    WHEN 'revoked'  THEN 'REVOKED'
+                                END
+        ) = 0
+        THEN RAISE(ABORT, 'approvals: status change requires a preceding event in approval_events')
+    END;
+END;

package/scripts/migrations/v19_to_v20.sql

@@ -0,0 +1,20 @@
+-- Migration v19 -> v20: add multi_use and confirmed columns to approval_grants.
+--
+-- These two columns support the upcoming FS-grant-plane migration:
+--   multi_use INTEGER NOT NULL DEFAULT 0  -- 1 = multi-use grant, 0 = single-use (BOOLEAN)
+--   confirmed INTEGER NOT NULL DEFAULT 0  -- 1 = grant confirmed by user, 0 = pending (BOOLEAN)
+--
+-- Both columns use the established boolean-as-INTEGER convention (DEFAULT 0)
+-- already in use across this schema (e.g. allow_write, can_read, can_write).
+--
+-- SQLite ALTER TABLE ADD COLUMN is safe and additive: existing rows receive the
+-- DEFAULT value and the table is NOT rebuilt.  Zero data loss is guaranteed by
+-- the SQLite specification (https://www.sqlite.org/lang_altertable.html).
+--
+-- Bootstrap note: migrations run once via the version chain.  A fresh install
+-- seeds from schema.sql (which already includes both columns) and then skips
+-- this migration file by version-gating; this file runs only against existing
+-- DBs initialized before v20 (which do not yet have these columns).
+
+ALTER TABLE approval_grants ADD COLUMN multi_use INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE approval_grants ADD COLUMN confirmed INTEGER NOT NULL DEFAULT 0;

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

@@ -14,6 +14,20 @@ through the hook layer, to the orchestrator when a T3 command is blocked: the
 the status and event vocabularies, and how to confirm a grant is active. The
 tables below are the canonical schema -- relay them verbatim, do not author them.
 
+The orchestrator presents this contract to the user from a **trusted source**,
+never by dispatching a subagent to verify or derive it (it has no shell). The
+primary source is the per-turn `[PENDING-APPROVALS-VERIFIED]` block injected at
+`UserPromptSubmit` (`build_verified_pending_approvals` in
+`hooks/modules/session/session_manifest.py`), which carries every pending that
+has survived >= 1 turn, each already DB-read and fingerprint-verified
+(`verified: true`). For a pending emitted in the current turn -- not yet in the
+block -- the fallback is the subagent's relayed `approval_request`. The
+**integrity boundary is grant activation**, not presentation:
+`verify_fingerprint` (`gaia/approvals/chain.py`) runs when the user selects the
+Approve label, so a tampered payload fails to form a grant regardless of how it
+was presented. See `Skill('orchestrator-present-approval')` for the presentation
+discipline.
+
 For the universal response envelope (`plan_status` states, `evidence_report`),
 see `agent-protocol`. For the deep mechanics -- fingerprint canonicalization,
 the hash chain, grant activation, reading a granted approval from Python -- see
@@ -21,10 +35,20 @@ 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 (minted at
+SubagentStop intake), and once the pending has survived a turn the orchestrator
+reads that id directly from the injected `[PENDING-APPROVALS-VERIFIED]` block
+(no derive-dispatch, no DB search); the singular id is random and the subagent
+relays it directly for the same-turn case. 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 +79,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 +96,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 +105,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` | 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 |
 
-`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.
+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
 
@@ -90,9 +122,13 @@ not assume an `EXECUTED` event exists after a command runs.
 - `SHOWN` precedes `APPROVED`; the activation path writes them together.
 - `approval_events` is append-only -- the `bu_approval_events_immutable` and
   `bd_approval_events_immutable` triggers `RAISE(ABORT)` on UPDATE/DELETE.
-- The orchestrator MUST re-verify a relayed payload via
-  `chain.verify_fingerprint(approval_id, payload_json, con)` before presenting;
-  a mismatch raises `ChainTamperError` and the approval aborts.
+- The payload's integrity is enforced at grant **activation**, not at
+  presentation: `chain.verify_fingerprint(approval_id, payload_json, con)` runs
+  when the user selects the Approve label, and a mismatch raises
+  `ChainTamperError` so the grant never forms. The orchestrator presents from a
+  trusted source (the injected `[PENDING-APPROVALS-VERIFIED]` block, already
+  fingerprint-verified by the hook; or a same-turn relayed `approval_request`)
+  and never dispatches a subagent to verify or derive the approval.
 
 For the grant activation walk-through, fingerprint internals, reading a granted
 approval from Python, and the retry-blocked-again diagnosis, see `reference.md`.

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

@@ -12,12 +12,17 @@ canonical string. `store.insert_requested()` stores both the canonical JSON
 (`payload_json`) and the hex fingerprint on the `approvals` row and on the
 `REQUESTED` event.
 
-The orchestrator MUST re-verify via
-`chain.verify_fingerprint(approval_id, payload_json, con)` before presenting.
-That function re-parses and re-canonicalizes the relayed `payload_json`,
-recomputes the fingerprint, and compares it against the fingerprint stored on
-the `REQUESTED` event. A mismatch raises `ChainTamperError` and the approval
-aborts -- this is a security boundary, not a recoverable UX issue.
+The fingerprint is verified at grant **activation**, not at presentation.
+`chain.verify_fingerprint(approval_id, payload_json, con)` re-parses and
+re-canonicalizes the payload, recomputes the fingerprint, and compares it
+against the fingerprint stored on the `REQUESTED` event; a mismatch raises
+`ChainTamperError` and the grant never forms -- a security boundary, not a
+recoverable UX issue. The per-turn `[PENDING-APPROVALS-VERIFIED]` builder
+(`build_verified_pending_approvals`) applies the same check when assembling the
+injected block, so only fingerprint-clean pendings reach the orchestrator marked
+`verified: true`. The orchestrator therefore presents from that already-verified
+block (or a same-turn relayed `approval_request`) and never dispatches to verify
+the payload itself.
 
 ## Hash chain
 
@@ -27,9 +32,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/reference.md

@@ -109,7 +109,7 @@ The package ships a single `gaia` binary (`bin/gaia.js`) that dispatches to Pyth
 | `gaia memory` | `bin/cli/memory.py` | Episodic memory: FTS5 search, show episode, health checks |
 | `gaia metrics` | `bin/cli/metrics.py` | Usage analytics: tier classification, agent invocations, anomaly counters |
 | `gaia paths` | `bin/cli/paths.py` | Inspect canonical Gaia storage paths (DB, plugin root, workspace) |
-| `gaia plans` | `bin/cli/plans.py` | List and display briefs/plans with status info |
+| `gaia plan` | `bin/cli/plan.py` | Manage plans (one per brief, DB-canonical): save, show, list, status |
 | `gaia workspace` | `bin/cli/workspace.py` | Workspace identity and consolidate operations |
 | `gaia scan` | `bin/cli/scan.py` | In-process project scan: detect stack, sync results to ~/.gaia/gaia.db (DB-canonical; no project-context.json written) |
 | `gaia status` | `bin/cli/status.py` | Quick installation snapshot: version, mode, DB path, registered workspace, last scan |
@@ -289,7 +289,7 @@ After `npm install -g @jaguilar87/gaia` (or via the local symlink) the dispatche
 | `gaia history` | Session history viewer | Debugging past sessions |
 | `gaia memory` | Episodic memory inspect/search | Recall past episodes, memory health |
 | `gaia approvals` | List/accept/reject pending T3 approvals | Approval workflow |
-| `gaia brief` / `gaia plans` | Brief and plan management against the DB substrate | Planning, brief lifecycle |
+| `gaia brief` / `gaia plan` | Brief and plan management against the DB substrate | Planning, brief lifecycle |
 | `gaia context` | Display and refresh project context | Audit context state |
 | `gaia paths` | Print resolved storage paths | Path debugging |
 | `gaia workspace` | Workspace identity and consolidate operations | Multi-workspace setups |