@jaguilar87/gaia 5.0.8 → 5.0.10

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

@@ -911,6 +911,57 @@ class BashValidator:
             reason="Safe by elimination (not blocked, not mutative)",
         )
 
+    def _is_ungranted_t3_component(
+        self, component: str, session_id: str
+    ) -> bool:
+        """Classify a chain component as ungranted-T3 WITHOUT minting or consuming.
+
+        Returns True when the component is a T3 (mutative-verb or
+        flag-dependent) operation for which NO active grant exists -- i.e. the
+        component would, on its own, be blocked pending approval. This is a
+        read-only probe used by the chain COMMAND_SET intake (AC-8) to decide
+        whether >= 2 sub-commands need grouping under ONE consent, BEFORE any
+        per-component minting happens.
+
+        It deliberately does NOT call decide_t3_outcome (no pending minted) and
+        does NOT consume any grant (match_command_set_grant /
+        check_approval_grant are pure lookups; consumption happens later in the
+        real _validate_single_command pass at retry). A component that already
+        matches a COMMAND_SET or semantic grant is treated as NOT ungranted, so
+        it is excluded from a fresh batch.
+        """
+        component = component.strip()
+        if not component:
+            return False
+
+        # Is this T3 (mutative verb or flag-dependent mutation)?
+        detect = detect_mutative_command(component)
+        is_t3 = detect.is_mutative
+        if not is_t3:
+            flag_result = classify_by_flags(component)
+            if (
+                flag_result is not None
+                and flag_result.outcome == FLAG_MUTATIVE
+                and not flag_result.command_family.startswith("git_")
+            ):
+                is_t3 = True
+        if not is_t3:
+            return False
+
+        # Already covered by an active grant? Then it is NOT ungranted -- exclude
+        # it from a fresh batch (pure lookups, no consumption).
+        try:
+            if match_command_set_grant(component) is not None:
+                return False
+        except Exception:
+            pass
+        try:
+            if check_approval_grant(component, session_id=session_id) is not None:
+                return False
+        except Exception:
+            pass
+        return True
+
     def _validate_compound_command(
         self,
         components: List[str],
@@ -918,9 +969,68 @@ class BashValidator:
         session_id: str = "",
         agent_type: str = "",
     ) -> BashValidationResult:
-        """Validate a compound command (multiple components)."""
+        """Validate a compound command (multiple components).
+
+        Chain COMMAND_SET intake (AC-8): when a chain ``a && b && c`` has TWO OR
+        MORE sub-commands that are ungranted T3, classifying them one-at-a-time
+        mints a single-signature pending for the FIRST and short-circuits -- so
+        one approval covers only the first sub-command and the next re-blocks
+        (the double-approval the user hit). To group them, a NON-MINTING
+        classification pass runs FIRST (``_is_ungranted_t3_component``); if >= 2
+        sub-commands are ungranted-T3 (and we are a subagent under the
+        orchestrator), ONE COMMAND_SET pending is minted over exactly those T3
+        sub-commands via ``decide_t3_outcome(command_set=...)``. One approval
+        then covers the chain; each sub-command is still consumed byte-for-byte
+        by its own signature at retry (no consent is widened -- the commands are
+        only grouped). Critically, the per-component minting path
+        (_validate_single_command) is NEVER entered for the batch, so no stray
+        single pendings are minted alongside the COMMAND_SET.
+
+        For every other shape (0 or 1 ungranted-T3, no orchestrator above, or a
+        component that is hard-blocked) the original per-component pass runs
+        unchanged: a hard block fails the chain fast, a lone T3 keeps the
+        singular grant path, and an all-granted/safe chain is allowed.
+        """
         logger.info(f"Compound command detected with {len(components)} components")
 
+        # NON-MINTING pre-pass: which components are ungranted T3? (AC-8)
+        if is_subagent and is_ops_mode():
+            ungranted_t3_idx = [
+                idx
+                for idx, comp in enumerate(components)
+                if self._is_ungranted_t3_component(comp, session_id)
+            ]
+            if len(ungranted_t3_idx) >= 2:
+                chain_set = [
+                    {"command": components[idx].strip(), "rationale": ""}
+                    for idx in ungranted_t3_idx
+                ]
+                first_cmd = chain_set[0]["command"]
+                first_detect = detect_mutative_command(first_cmd)
+                verb = first_detect.verb or "command"
+                category = first_detect.category or "MUTATIVE"
+                native_ask_reason = (
+                    f"[T3_APPROVAL_REQUIRED] Chain of {len(chain_set)} T3 commands.\n"
+                    f"Commands:\n"
+                    + "\n".join(f"  - {it['command']}" for it in chain_set)
+                )
+                logger.info(
+                    "Chain COMMAND_SET intake: %d T3 sub-commands grouped under "
+                    "one consent (chain=%s)",
+                    len(chain_set),
+                    " && ".join(it["command"][:30] for it in chain_set),
+                )
+                return decide_t3_outcome(
+                    first_cmd,
+                    verb=verb,
+                    category=category,
+                    has_orchestrator_above=True,
+                    native_ask_reason=native_ask_reason,
+                    session_id=session_id,
+                    agent_type=agent_type,
+                    command_set=chain_set,
+                )
+
         component_results: List[BashValidationResult] = []
         for i, component in enumerate(components, 1):
             result = self._validate_single_command(
@@ -1385,6 +1495,7 @@ def decide_t3_outcome(
     native_ask_reason: str,
     session_id: str = "",
     agent_type: str = "",
+    command_set: list | None = None,
 ) -> BashValidationResult:
     """Single decision point for the outcome of a T3 (state-mutating) command.
 
@@ -1416,34 +1527,68 @@ def decide_t3_outcome(
         native_ask_reason: Reason text for the native-ask fallback branch.
         session_id: Session ID for pending-approval scoping.
         agent_type: Originating agent name (for the sealed payload).
+        command_set: Optional list of ``{command, rationale}`` dicts. When it
+            carries MORE THAN ONE item, this T3 decision covers a chain
+            (``a && b && c``) whose sub-commands are all T3, and the pending is
+            minted as ONE COMMAND_SET envelope (the chain-intake path, AC-8)
+            instead of a single semantic-signature pending. ONE user approval
+            then covers the whole chain; each sub-command is still consumed
+            byte-for-byte by its own signature at retry. A None / single-item
+            set keeps the singular behaviour. Only honoured in the
+            subagent-under-orchestrator branch (the native-ask branch has no
+            COMMAND_SET concept).
 
     Returns:
         A blocked BashValidationResult (allowed=False, tier T3) whose
         block_response is either a "deny" (with approval_id) or an "ask".
     """
+    # A genuine multi-command chain is a set of >= 2 items. Anything else
+    # collapses to the singular path so we never mint a COMMAND_SET for one
+    # command (mirrors _build_sealed_payload's is_command_set guard).
+    _normalized_set: list = []
+    if command_set:
+        for _item in command_set:
+            if isinstance(_item, dict) and _item.get("command"):
+                _normalized_set.append(
+                    {
+                        "command": _item["command"],
+                        "rationale": _item.get("rationale", ""),
+                    }
+                )
+    is_chain_command_set = len(_normalized_set) > 1
+
     if has_orchestrator_above:
         # Subagent-under-orchestrator: deny + persisted approval_id so the
         # orchestrator can run the approval cycle.  Reuse an existing pending
         # approval on retry to avoid generating duplicates while the user reviews.
-        approval_id = _find_pending_in_db(session_id or "", command)
-        if approval_id:
-            logger.info(
-                "Reusing pending approval_id=%s for retry: %s",
-                approval_id, command[:80],
-            )
-            reason = build_t3_blocked_denial_message(
-                approval_id=approval_id,
-                command=command,
-                verb=verb,
-                category=category,
-            )
-            hook_deny = build_hook_permission_response("deny", reason)
-            return BashValidationResult(
-                allowed=False,
-                tier=SecurityTier.T3_BLOCKED,
-                reason=f"T3 {category.lower()} command: {command[:60]}",
-                block_response=hook_deny,
-            )
+        #
+        # For a COMMAND_SET chain the pending id is CONTENT-derived (matching the
+        # plan-first intake), so a retry of the same chain produces the same id
+        # and the fingerprint-dedup in insert_requested reuses the pending. The
+        # singular reuse probe (_find_pending_in_db) matches a SINGLE command's
+        # signature and must NOT be consulted for the chain -- it would match one
+        # leftover single pending of a sub-command and degrade the chain back to
+        # a single grant. So the chain path skips it entirely.
+        if not is_chain_command_set:
+            approval_id = _find_pending_in_db(session_id or "", command)
+            if approval_id:
+                logger.info(
+                    "Reusing pending approval_id=%s for retry: %s",
+                    approval_id, command[:80],
+                )
+                reason = build_t3_blocked_denial_message(
+                    approval_id=approval_id,
+                    command=command,
+                    verb=verb,
+                    category=category,
+                )
+                hook_deny = build_hook_permission_response("deny", reason)
+                return BashValidationResult(
+                    allowed=False,
+                    tier=SecurityTier.T3_BLOCKED,
+                    reason=f"T3 {category.lower()} command: {command[:60]}",
+                    block_response=hook_deny,
+                )
 
         # No existing pending -- insert via DB (D16: exclusive path).
         sealed_payload = _build_sealed_payload(
@@ -1451,13 +1596,25 @@ def decide_t3_outcome(
             verb=verb,
             category=category,
             agent_type=agent_type,
+            command_set=_normalized_set if is_chain_command_set else None,
         )
         try:
             from gaia.approvals.store import insert_requested
+            # COMMAND_SET chains use a CONTENT-derived id (deterministic over the
+            # sub-command list) so a retry of the same chain reproduces the same
+            # id and reuses the pending via fingerprint dedup -- identical to the
+            # plan-first intake in handoff_persister. Singular T3 keeps uuid4.
+            supplied_id = None
+            if is_chain_command_set:
+                from gaia.approvals.store import derive_command_set_id
+                supplied_id = derive_command_set_id(
+                    [it["command"] for it in _normalized_set]
+                )
             approval_id = insert_requested(
                 sealed_payload,
                 agent_id=agent_type or None,
                 session_id=session_id or None,
+                approval_id=supplied_id,
             )
         except Exception as _store_err:
             logger.warning(

package/dist/gaia-ops/hooks/post_compact.py

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

package/dist/gaia-ops/hooks/pre_compact.py

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

package/dist/gaia-ops/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/dist/gaia-ops/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
@@ -27,10 +41,12 @@ For a **singular** T3 approval (the hook-block path),
 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
+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]`.
 
@@ -106,9 +122,13 @@ whose command never ran, or that ran through the redirect-sanitized path.
 - `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/dist/gaia-ops/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
 

package/dist/gaia-ops/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 |

package/dist/gaia-ops/skills/orchestrator-present-approval/SKILL.md

@@ -15,11 +15,13 @@ names the specific action. No exceptions. No brevity shortcuts.
 ```
 
 `orchestrator-present-approval` is the discipline the orchestrator follows when
-a subagent emits `APPROVAL_REQUEST` with an `approval_id`: relay the
-`sealed_payload` into AskUserQuestion -- fingerprint check, mandatory fields in
-the question, mandatory nonce in the option label. For the subagent side that
-produced the payload see `subagent-request-approval`; for the data contract
-itself see `agent-approval-protocol`.
+an approval needs the user's consent: relay the sealed fields into
+AskUserQuestion -- mandatory fields in the question, mandatory nonce in the
+option label. The orchestrator has no shell, so it never dispatches a subagent
+to derive or verify an approval; it presents from a trusted source it already
+holds. For the subagent side that produced the payload see
+`subagent-request-approval`; for the data contract itself see
+`agent-approval-protocol`.
 
 ## Mental Model
 
@@ -27,25 +29,53 @@ The orchestrator sits between the subagent and the user. The user cannot make
 an informed decision on data they have not seen -- a summary, a reference to
 "the plan above", or an offer to show details on request all push the decision
 without the data needed to decide. The job is **verbatim relay, not
-re-authoring**: rewriting any of the 7 sealed fields breaks the fingerprint and
-`verify_fingerprint` (`gaia/approvals/chain.py`) raises `ChainTamperError`.
-
-## Step 0 -- Verify the approval against the DB (mandatory before SHOWN)
-
-A subagent's reported `approval_id` is an unverified claim, not a fact. The agent runs in its own context and can relay an id that is stale, from another session, or simply wrong -- and a stale id presented as a fresh block walks the user into consenting to nothing real (or to a grant that no longer exists). The DB is the source of truth; the agent's report is a pointer into it that you must resolve, never the authority itself.
-
-So before AskUserQuestion, two checks against the DB, in order:
-
-1. **The approval exists, is fresh, and is from the current session.** Query `gaia approvals pending --session "$CLAUDE_SESSION_ID"` (or `--json` for parsing). The reported `approval_id` MUST appear in that result. If it appears only under `--all-sessions` but not the current session, it is leakage from another session (a test session such as `e2e-sim`, a prior run) -- **do not present**. If it does not appear at all, it does not exist or was already consumed/rejected -- **do not present**. Freshness is the `created_at` of the pending row plus its presence as still-`pending`; an id the agent reports that is not currently pending in *this* session is not a fresh block, whatever the agent says.
-2. **The payload is untampered.** Call `verify_fingerprint(approval_id, payload_json, con) -> bool` from `gaia/approvals/chain.py`. It raises `ChainTamperError` if the payload was modified between subagent emission and your relay (security boundary, do not present), and `ValueError` if no REQUESTED event exists for this `approval_id`. Either case: **do not present**, report the failure, stop.
-
-**For a `command_set` (plan-first batch) the agent does not know the id at all -- so you DERIVE it deterministically, you do not search the DB.** The hook mints the `approval_id` at SubagentStop (`_intake_command_set_pending` -- see Rule 3) from the **content** of the command_set, not from a uuid4. The id is `P-<first 32 hex of sha256(canonical(command list))>` (`derive_command_set_id` in `gaia/approvals/store.py`). Because it is content-derived, you reproduce the EXACT minted id from the `command_set` you already hold in the contract -- with **no `gaia approvals pending --session` search**. Run:
-
-```
-gaia approvals derive-id --commands-json '<the command_set from the contract>'
-```
-
-It applies the SAME mutative filter the intake used and prints the `P-...` id (the same function `derive_command_set_id` the hook minted with). This closes the cross-session miss: the SubagentStop output never reaches the parent (Claude Code issue #5812), so a random id could not be recovered across sessions -- a content-derived one needs no recovery at all. Having derived the id, run Step 0's existence/fingerprint checks against it exactly as for a singular id (the row is now findable by that exact id). The shape: the DB mints content-derived, the orchestrator re-derives, the agent never owns the id and no search is needed.
+re-authoring**: rewriting any of the sealed fields would change the consent
+surface from what was recorded. Integrity of the payload is enforced at grant
+**activation** (`verify_fingerprint` in `gaia/approvals/chain.py`, called when
+the user selects the Approve label), not at presentation -- so presentation
+itself never needs a verify-dispatch.
+
+## Step 0 -- Present from a trusted source; never dispatch to verify or derive
+
+The orchestrator has no shell. It MUST NOT dispatch a subagent solely to derive
+or verify an approval before presenting -- that dispatch is both unnecessary
+(the integrity check runs at activation, below) and harmful (its SubagentStop
+can sweep the very pending being verified). Instead, present from one of two
+**trusted** sources:
+
+1. **Primary -- the injected `[PENDING-APPROVALS-VERIFIED]` block.** A per-turn
+   hook (`hooks/modules/session/session_manifest.py`) injects, on every
+   `UserPromptSubmit`, every pending that has survived >= 1 turn. Each row in
+   that block has already been DB-read and fingerprint-verified by the hook
+   (`build_verified_pending_approvals` -- only rows whose payload re-canonicalizes
+   to the fingerprint stored on their `REQUESTED` event appear, each marked
+   `verified: true`). **Present directly from this block** -- the fields, the
+   full `approval_id`, and (for batches) the whole `command_set` with its minted
+   id are all there. No DB query, no `derive-id`, no dispatch.
+2. **Fallback -- same-turn relay.** A pending a subagent emits during the
+   CURRENT turn will not be in this turn's block yet: the block is built at
+   `UserPromptSubmit`, before the subagent ran. For that case present from the
+   subagent's relayed `approval_request`. This is justified because the pending
+   was freshly minted in THIS session by a trusted dispatch, AND integrity is
+   enforced at grant **activation** (`verify_fingerprint` fires when the user
+   selects the Approve label), not at presentation. The old pre-presentation
+   verify was redundant belt-and-suspenders; it is removed.
+
+Once the pending survives a turn it appears in the injected block, so the relay
+is only ever needed for the same-turn case.
+
+**For a `command_set` (plan-first batch) you do not derive the id -- you read it
+from the block.** The hook mints the `approval_id` at SubagentStop
+(`_intake_command_set_pending` -- see Rule 3) from the **content** of the
+command_set (`derive_command_set_id` in `gaia/approvals/store.py`,
+`P-<first 32 hex of sha256(canonical(command list))>`). Once that pending has
+survived a turn, the `[PENDING-APPROVALS-VERIFIED]` block carries it with its
+minted `approval_id` and all N commands already attached -- so you read the id
+and the commands straight from the block. **No `gaia approvals derive-id`
+dispatch is needed.** For a command_set emitted in the CURRENT turn (not yet in
+the block), present from the subagent's relayed `approval_request`, which carries
+the same `command_set`; the content-derived id reaches you when the pending
+appears in the next turn's block.
 
 ## Mandatory presentation -- 5 labeled fields + nonce-suffixed label
 
@@ -72,7 +102,13 @@ whose `id` starts with `P-{prefix}`. Without the suffix no grant is created.
 See `template.md` for the canonical layout and `reference.md` -> "GOOD vs BAD
 Examples" for full presentations.
 
-Fields above are extracted from the DB-stored canonical payload (`payload_json` on the REQUESTED row), not from the subagent's relayed `approval_request` — that's why `rollback_hint` is the field name here while the subagent contract uses `rollback`.
+Fields above are extracted from your trusted source. From the injected
+`[PENDING-APPROVALS-VERIFIED]` block (the primary path) they appear under the
+canonical names shown here (`operation`, `exact_content`, `scope`, `risk_level`,
+`rationale`, `rollback_hint`). From a same-turn relayed `approval_request` (the
+fallback) the rollback field arrives under the key `rollback` -- map it to
+ROLLBACK the same way. Either way you copy values verbatim; you do not re-author
+them.
 
 ## Rules
 
@@ -90,7 +126,12 @@ Fields above are extracted from the DB-stored canonical payload (`payload_json`
    `APPROVAL_REQUEST` carrying a `command_set` of >= 2 `{command, rationale}`
    items and **no** `approval_id`, the SubagentStop processor
    (`handoff_persister._intake_command_set_pending`) mints ONE pending
-   `COMMAND_SET` with one `approval_id`. You present that single approval: list
+   `COMMAND_SET` with one content-derived `approval_id`. Once that pending has
+   survived a turn it appears in the injected `[PENDING-APPROVALS-VERIFIED]`
+   block with its minted `approval_id` and all N commands -- **read the id and
+   commands from the block; do not dispatch `gaia approvals derive-id`.** (A
+   command_set emitted in the current turn is presented from the subagent's
+   relayed `approval_request`.) You present that single approval: list
    **all N commands** in the question body, but use **one** Approve label with
    **one** `[P-{nonce8}]` suffix -- one consent covers the whole batch. On
    approval, `activate_db_pending_by_prefix` Step 3b creates a single
@@ -126,5 +167,5 @@ wording, see `reference.md` -> "GOOD vs BAD Examples", "Option Label Patterns",
 | "Similar command, slightly different path -- I'll reuse / wrap it" | Grants match the statement signature byte-for-byte. Any wrapper, redirect, flag, or path drift is a different signature and a fresh re-block. |
 | "The same command emitted a new approval_id" | Grants are single-use and consumed on the first retry. A second run is a new APPROVAL_REQUEST -- approve again. |
 | "I'll set batch_scope to approve many at once" | `batch_scope` is ignored -- but a real batch path exists: a plan-first `command_set` (>= 2 items, no `approval_id`) is intaken into ONE pending `COMMAND_SET`. Present that single approval (N commands shown, one `[P-...]` nonce, one consent), not N separate approvals. |
-| "I can paraphrase a field before relaying" | The fingerprint covers all 7 sealed fields; any modification raises `ChainTamperError` in Step 0 and the presentation is refused. |
-| **"The agent reported an `approval_id`, so it's a real fresh block"** -- trusting a nonce relayed by the subagent | The agent's reported id is an unverified pointer, not a fact. It can be stale or belong to another session -- subagents have presented a STALE nonce from a test session (`e2e-sim`) as if it were a fresh block. Resolve every reported id against `gaia approvals pending --session "$CLAUDE_SESSION_ID"` (Step 0): it must be currently pending in *this* session. Visible only under `--all-sessions`, or absent entirely, means do not present. For `command_set` the hook mints the id and the agent never has one -- you **derive** it deterministically from the command_set via `gaia approvals derive-id` (content-derived, no DB search), then run the same existence/fingerprint checks. |
+| "I can paraphrase a field before relaying" | The fingerprint covers all sealed fields and is checked at grant **activation** (`verify_fingerprint`, when the user selects the Approve label); a paraphrase there raises `ChainTamperError` and the grant never forms. Relay verbatim so activation succeeds. |
+| **"I'll dispatch a subagent to verify or derive the approval before presenting"** | The orchestrator has no shell and must NEVER dispatch to verify or derive an approval. The pending arrives **already verified** in the injected `[PENDING-APPROVALS-VERIFIED]` block (DB-read + fingerprint-checked by the per-turn hook, `verified: true`) -- present from it. For a same-turn pending not yet in the block, present from the subagent's relayed `approval_request`. A verify/derive dispatch is unnecessary (integrity is enforced at activation) and harmful (its SubagentStop can sweep the very pending). For `command_set`, read the minted `approval_id` and all commands from the block -- do not run `gaia approvals derive-id`. |

package/dist/gaia-ops/skills/orchestrator-present-approval/reference.md

@@ -151,6 +151,16 @@ commands** in the question body, with **one** Approve label carrying **one**
 `[P-{nonce8}]` suffix. The user gives one consent; each command then runs on its
 own retry within the 60-minute window. You do NOT issue N separate approvals.
 
+**Reading the batch id and commands -- from the block, not by dispatch.** Once
+the minted `COMMAND_SET` pending has survived a turn, it appears in the injected
+`[PENDING-APPROVALS-VERIFIED]` block with its content-derived `approval_id` and
+all N commands attached (`build_verified_pending_approvals` in
+`hooks/modules/session/session_manifest.py`). Read the id and the commands
+straight from that block -- the orchestrator has no shell and must NOT dispatch
+`gaia approvals derive-id` or any verify command. For a command_set emitted in
+the CURRENT turn (not yet in the block), present from the subagent's relayed
+`approval_request`, which carries the same `command_set`.
+
 ## Grant Activation Mechanics
 
 When the hook blocks a T3 Bash command in subagent context,
@@ -161,9 +171,12 @@ generates a `P-{uuid4_hex}` `approval_id`, fingerprints the payload, inserts an
 message ends with `approval_id: P-{...}` (`build_t3_blocked_denial_message` in
 `hooks/modules/security/approval_messages.py`).
 
-The subagent relays that `approval_id` in its `approval_request`. The
-orchestrator presents via AskUserQuestion with the `[P-xxxxxxxx]` label. When
-the user selects the Approve label, the **ElicitationResult hook**
+The orchestrator presents via AskUserQuestion with the `[P-xxxxxxxx]` label,
+reading the `approval_id` and fields from the injected
+`[PENDING-APPROVALS-VERIFIED]` block (primary) or, for a same-turn pending not
+yet in the block, from the subagent's relayed `approval_request` (fallback). It
+does not dispatch to verify or derive. When the user selects the Approve label,
+the **ElicitationResult hook**
 (`hooks/elicitation_result.py`) fires and calls
 `activate_db_pending_by_prefix()`, which:
 

package/dist/gaia-ops/skills/orchestrator-present-approval/template.md

@@ -1,8 +1,12 @@
 # AskUserQuestion Template
 
 Use this layout verbatim when presenting an approval to the user. Replace
-`{...}` placeholders with values extracted from the subagent's `sealed_payload`
-and `approval_request`. Do not paraphrase, summarize, or omit any field.
+`{...}` placeholders with values read from your trusted source -- the injected
+`[PENDING-APPROVALS-VERIFIED]` block (primary; already DB-read and
+fingerprint-verified by the per-turn hook) or, for a same-turn pending not yet
+in the block, the subagent's relayed `approval_request` (fallback). Never
+dispatch a subagent to derive or verify the approval. Do not paraphrase,
+summarize, or omit any field.
 
 ## Standard Approval (single command)
 
@@ -23,8 +27,9 @@ AskUserQuestion(
 )
 ```
 
-Where `approval_id_prefix8` is the first 8 characters of the `approval_id`
-field from the subagent's `approval_request` (after the `P-` prefix).
+Where `approval_id_prefix8` is the first 8 characters (after the `P-` prefix) of
+the `approval_id` read from the `[PENDING-APPROVALS-VERIFIED]` block, or from the
+subagent's `approval_request` for a same-turn pending.
 
 ## Batch template (COMMAND_SET)
 
@@ -47,4 +52,4 @@ ignored -- the signal is the presence of `command_set` in the contract.
 | SCOPE | `sealed_payload.scope` |
 | RIESGO | `sealed_payload.risk_level` + `sealed_payload.rationale` |
 | ROLLBACK | `sealed_payload.rollback_hint` (null -> "NOT REVERSIBLE") |
-| Option nonce suffix | `approval_request.approval_id` first 8 chars after `P-` |
+| Option nonce suffix | `approval_id` first 8 chars after `P-` (from the `[PENDING-APPROVALS-VERIFIED]` block, or `approval_request.approval_id` for a same-turn pending) |