@jaguilar87/gaia 5.0.2 → 5.0.4

package/dist/gaia-ops/skills/agent-response/SKILL.md

@@ -16,7 +16,7 @@ The orchestrator loads this to interpret a returned `agent_contract_handoff` and
 
 ```
 parse_contract(agent_output)  ->  read agent_status.plan_status
-  |- COMPLETE         -> summarize key_outputs + surface verification, then close
+  |- COMPLETE         -> relay user_facing_summary if present & N=1, else summarize key_outputs; surface verification, then close
   |- APPROVAL_REQUEST -> split on approval_id (present: present-approval; absent: plan options)
   |- NEEDS_INPUT      -> AskUserQuestion, then SendMessage the answer
   |- BLOCKED          -> present open_gaps; new dispatch or accept the limitation
@@ -29,7 +29,7 @@ Before any branch runs, the contract must parse. A block that fails `parse_contr
 
 | `plan_status` | Action |
 |---|---|
-| `COMPLETE` | Summarize `key_outputs` in 3-5 bullets AND surface `verification.result` / `verification.details` -- that block is the proof the work landed, and relaying it is what lets the user trust the increment rather than take "done" on faith. Mention `cross_layer_impacts` and `open_gaps` when non-empty. |
+| `COMPLETE` | If `user_facing_summary` is present AND this is a single-agent turn (N=1), relay it near-verbatim -- adapt only to the user's language, do not re-synthesize -- because the subagent already wrote the human-shaped summary and re-summarizing its `key_outputs` only spends tokens to restate what it said. If the field is absent, or N>1 (multiple agents being consolidated), summarize `key_outputs` in 3-5 bullets as before. Either way, surface `verification.result` / `verification.details` -- that block is the proof the work landed, and relaying it is what lets the user trust the increment rather than take "done" on faith. Mention `cross_layer_impacts` and `open_gaps` when non-empty. |
 | `APPROVAL_REQUEST` | Split on `approval_request.approval_id`: present -> load `Skill('orchestrator-present-approval')`; absent -> present the plan with options (execute / modify / cancel) and on execute/modify resume the SAME agent via `SendMessage`. It splits because a hook-issued `approval_id` carries a pending T3 grant that needs the structured consent flow, while a plan-first request only needs direction (`agent-approval-protocol`, combo decision 2). |
 | `NEEDS_INPUT` | `AskUserQuestion` with the options in `next_action`, then `SendMessage` the answer back to resume. |
 | `BLOCKED` | Present `open_gaps` to the user. If they give direction, dispatch a NEW agent addressing the blocker; if they accept the limitation, close the task as incomplete and move on. |
@@ -41,6 +41,8 @@ These ride alongside `plan_status` and carry signal the orchestrator loses if it
 
 **`verification`** -- covered in COMPLETE above. It is required only on `COMPLETE` and its `result` must equal `"pass"` (`VERIFICATION_RESULT_MUST_BE_PASS`, `contract_validator.py`); surface `result` and `details` so the user sees the proof, never just the word "done."
 
+**`user_facing_summary`** -- the one human-audience field (every other field is machine-audience for the orchestrator). On a single-agent `COMPLETE` it is what you relay to the user, near-verbatim and language-adapted, *instead of* re-synthesizing `key_outputs`; that is the whole point -- the subagent wrote the summary once, so re-summarizing duplicates work the user never sees value in. It is optional and additive: when absent, fall back to `key_outputs`; when multiple agents are in flight (N>1), ignore it and synthesize across them, because no single agent's summary speaks for the consolidated result.
+
 **`memorialize_suggestions` / `memory_suggestions`** -- present each entry to the user before closing the turn and persist ONLY on consent. The orchestrator is the sole memory writer; subagents are blocked from curated writes by design so each entry enters the substrate as a named choice. For the curation mechanics -- how to triage, slug, and persist -- load `Skill('memory')` (combo decision 1: the HOW lives in `memory`).
 
 **`ownership_assessment`** (in `consolidation_report`, enum `VALID_OWNERSHIP_ASSESSMENTS`) -- a ROUTING INPUT the orchestrator acts on silently, not a user-facing field. `owned_here` means the output is authoritative; `cross_surface_dependency` or `not_my_surface` means another dispatch may be needed to close the gap. Route on it; do not narrate it (combo decision 4).

package/dist/gaia-ops/skills/gaia-patterns/reference.md

@@ -29,7 +29,7 @@ SessionStart emits a one-shot `hookSpecificOutput.additionalContext` manifest (E
 | Package | Files | Purpose |
 |---------|-------|---------|
 | `core/` | `hook_entry`, `paths`, `plugin_mode`, `plugin_setup`, `state`, `stdin` | Entry dispatch, path resolution, mode detection, shared state |
-| `security/` | `blocked_commands`, `mutative_verbs`, `tiers`, `gitops_validator`, `command_semantics`, `approval_grants`, `approval_scopes`, `approval_cleanup`, `approval_constants`, `approval_messages`, `blocked_message_formatter`, `prompt_validator` | T3 gate, blocked commands, approval nonce lifecycle |
+| `security/` | `blocked_commands`, `mutative_verbs`, `tiers`, `command_semantics`, `approval_grants`, `approval_scopes`, `approval_cleanup`, `approval_constants`, `approval_messages`, `blocked_message_formatter`, `prompt_validator` | T3 gate, blocked commands, approval nonce lifecycle |
 | `audit/` | `logger`, `metrics`, `event_detector`, `workflow_auditor`, `workflow_recorder` | Structured logging, metrics collection, workflow audit trail |
 | `tools/` | `bash_validator`, `cloud_pipe_validator`, `shell_parser`, `task_validator`, `hook_response` | Command validation, pipe detection, shell parsing |
 | `context/` | `context_injector`, `context_writer`, `context_freshness`, `contracts_loader`, `compact_context_builder`, `anchor_tracker` | Project-context injection, freshness checks, contract loading |
@@ -254,7 +254,7 @@ The hook invoker is `python3 <script>` rather than executing the script directly
 | Category | Directory | What it tests |
 |----------|-----------|---------------|
 | Prompt regression | `tests/layer1_prompt_regression/` | Routing table, skill content rules, agent frontmatter, agent prompts, security tier consistency, skills cross-reference, context contracts |
-| Hooks | `tests/hooks/modules/` | Security modules (mutative_verbs, blocked_commands, tiers, gitops_validator, approval_grants, approval_scopes, command_semantics), tools (bash_validator, shell_parser, cloud_pipe_validator, task_validator), core (paths, state), context (context_writer) |
+| Hooks | `tests/hooks/modules/` | Security modules (mutative_verbs, blocked_commands, tiers, approval_grants, approval_scopes, command_semantics), tools (bash_validator, shell_parser, cloud_pipe_validator, task_validator), core (paths, state), context (context_writer) |
 | System | `tests/system/` | Directory structure, permissions, agent definitions, configuration, schema compatibility |
 | Tools | `tests/tools/` | context_provider, episodic, pending_updates, deep_merge, review_engine, surface_router |
 | Integration | `tests/integration/` | Context enrichment, subagent lifecycle, subagent stop, nonce approval relay |

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

@@ -71,12 +71,27 @@ Fields above are extracted from the DB-stored canonical payload (`payload_json`
    grant consumed by the first retry (`consume_db_semantic_grant` in
    `gaia/store/writer.py`). A second invocation is a new APPROVAL_REQUEST.
 
-3. **No batch grant.** Legacy `verb_family` was removed; the `COMMAND_SET`
-   replacement has only the CHECK side wired (`match_command_set_grant` is
-   called by `bash_validator`, but `create_command_set_grant` has no production
-   caller). `batch_scope` is ignored. For N commands, expect N approvals.
+3. **Batch grant is `COMMAND_SET` -- one consent, N commands.** Legacy
+   `verb_family` was removed; its replacement, `COMMAND_SET`, is now wired
+   end-to-end (intake, activation, consume). When a subagent emits a plan-first
+   `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
+   **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
+   `COMMAND_SET` grant (60-min TTL); each command is consumed byte-for-byte on
+   its own retry. `batch_scope` is still ignored (the signal is `command_set`).
    See `reference.md` -> "On batch intents".
 
+   You present the batch the subagent chose to send; you do not steer it toward
+   batching. Whether grouping is warranted is the subagent's judgment (known
+   batch, >= 2, friction reduced -- see `subagent-request-approval`). A singular
+   approval arriving where you imagined a batch is not a defect to correct: the
+   default is just-in-time, and a batch you would have manufactured asks the
+   user to consent to commands that may never run.
+
 4. **Re-dispatch, do not resume.** `mode` does not survive a SendMessage resume:
    the resume runs in `default` and re-blocks the next protected operation even
    after the Gaia grant activated. Prefer a fresh re-dispatch with the same
@@ -97,5 +112,5 @@ wording, see `reference.md` -> "GOOD vs BAD Examples", "Option Label Patterns",
 | "I'll skip the [P-...] suffix, it's cosmetic" | The hook extracts the nonce from the label to find the right pending row; without it, targeted activation fails and no grant is created. |
 | "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" | No batch activation exists in current code -- the field is ignored. Each blocked command needs its own approval. |
+| "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. |

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

@@ -107,32 +107,49 @@ contain `[P-<hex>]`. Reject labels never carry a nonce. The captured hex is the
 `get_pending(all_sessions=True)` and selects the one whose `id` starts with
 `P-{prefix}`.
 
-## On batch intents -- there is no multi-use grant
+## On batch intents -- the COMMAND_SET grant (one consent, N commands)
 
 The old `verb_family` design (one approval covering many commands of the same
 `base_cmd + verb`) **was removed**. The module docstring in
 `hooks/modules/security/approval_grants.py` is explicit: "The legacy verb_family
 path has been removed."
 
-The intended replacement is the `COMMAND_SET` grant: an explicit list of
+Its replacement is the `COMMAND_SET` grant: an explicit list of
 `{command, rationale}` items, each matched **byte-for-byte** (D10: no whitespace
 normalization, no quote canonicalization, no shell expansion) and consumed
 individually (`create_command_set_grant` and `match_command_set_grant` in
 `approval_grants.py`).
 
-**Current state of the code:** only the CHECK side is wired. `bash_validator`
-(`hooks/modules/tools/bash_validator.py`) calls `match_command_set_grant()` and
-consumes a matched item, but **no production path calls
-`create_command_set_grant()`** -- it exists only in the module and its tests.
-The ElicitationResult / adapter activation paths (`hooks/elicitation_result.py`,
-`hooks/adapters/claude_code.py`) contain no "batch", "verb_family", "multi_use",
-or "command_set" handling; they only call `activate_db_pending_by_prefix()`,
-which creates a single-use `SCOPE_SEMANTIC_SIGNATURE` grant.
-
-**Practical consequence:** putting the word "batch" in a label, or a `batch_scope`
-field in an `approval_request`, does nothing. Each blocked command produces its
-own single-use semantic grant and its own approval. For a sweep of N commands,
-expect N approvals until the COMMAND_SET create path is wired.
+**Current state of the code: all three sides are wired -- intake, activation,
+consume.** It is a **plan-first** flow: the subagent declares the batch up-front
+by emitting an `APPROVAL_REQUEST` whose `approval_request` carries a
+`command_set` list and **no** `approval_id`.
+
+- **Intake.** The SubagentStop processor
+  `hooks/modules/agents/handoff_persister.py` ->
+  `_intake_command_set_pending()` reads the `command_set`; when it holds **>= 2**
+  items it calls `gaia.approvals.store.insert_requested()` with a payload that
+  contains the `command_set` key, minting **exactly ONE** pending `COMMAND_SET`
+  approval with one `approval_id`. A set of `<= 1` item is declined (no
+  COMMAND_SET is minted for one command).
+- **Activation.** When the user approves, `activate_db_pending_by_prefix()`
+  (`hooks/modules/security/approval_grants.py`) reads `payload["command_set"]`,
+  and because it has > 1 item branches at **Step 3b** into
+  `create_command_set_grant()`, inserting ONE `COMMAND_SET` grant row (status
+  `PENDING`, `command_set_json` holding the whole set, 60-min TTL via
+  `DEFAULT_COMMAND_SET_TTL_MINUTES`) instead of a singular
+  `SCOPE_SEMANTIC_SIGNATURE` grant.
+- **Consume.** On each retry, `bash_validator` calls `match_command_set_grant()`
+  (byte-for-byte index match), then `mark_command_set_item_consumed()`; a
+  consumed index never matches again (replay protection), and when every index
+  is consumed the grant flips to `CONSUMED`.
+
+**Practical consequence:** a `batch_scope` field still does nothing -- the signal
+is `command_set`. To approve a sweep of N related commands under one consent,
+present the single `COMMAND_SET` approval the intake minted: show **all N
+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.
 
 ## Grant Activation Mechanics
 

package/dist/gaia-ops/skills/security-tiers/SKILL.md

@@ -17,7 +17,11 @@ security-tiers classifies every operation into four tiers so an agent knows whet
 | **T0** | Read-only; observes state, changes nothing | No | get, list, describe, show, logs, status |
 | **T1** | Local validation; no remote calls, no state | No | validate, lint, fmt, check |
 | **T2** | Simulation / dry-run; may read remote, never writes | No | plan, diff, dry-run, template |
-| **T3** | State-mutating; creates, updates, or destroys | **Yes** | apply, create, delete, commit, push, deploy |
+| **T3** | State-mutating; creates, updates, or destroys | **Yes** | apply, create, delete, push, deploy |
+
+`git commit` and `git add` are **not** T3 -- they are local-only operations (they touch the working tree and local refs, never remote state), so they classify as safe by elimination. Only `git push` mutates remote state and is T3. This matches `GIT_LOCAL_SAFE_SUBCOMMANDS` in `mutative_verbs.py`, where `commit` and `add` are listed as local-safe.
+
+**T3 gates a direction, not a category of verb.** An operation needs consent because it moves the system toward *more* capability (it grants) or *less* recoverability (it destroys). An operation that only moves the other way -- that *reduces* capability already granted -- does not need consent, because the worst it can do is take back power that was given. So within Gaia's own consent layer, `gaia approvals revoke|reject|reject-all|clean` are **not** T3: they only revoke or discard grants Gaia itself issued, never reaching outside the local approval store. The asymmetry is deliberate -- `gaia approvals approve` *grants* capability without the AskUserQuestion flow, so it stays T3. This is anchored to the `gaia approvals` group in `CONSENT_REDUCING_SUBCOMMAND_EXCEPTIONS` (`mutative_verbs.py`), not generalized to every CLI's "revoke" -- a cloud IAM revoke is a real remote mutation and remains T3.
 
 ## Classification heuristic
 

package/dist/gaia-ops/skills/security-tiers/reference.md

@@ -36,7 +36,9 @@ Read on-demand by infrastructure agents. Not injected automatically.
 - `kubectl apply -f manifest.yaml`
 - `helm upgrade` (without `--dry-run`)
 - `flux reconcile` (write operations)
-- `git commit`, `git push` (any branch)
+- `git push` (any branch) -- mutates remote state
+
+Note: `git commit` and `git add` are **not** T3. They are local-only (working tree + local refs, never remote), classified safe by elimination via `GIT_LOCAL_SAFE_SUBCOMMANDS` in `mutative_verbs.py`. Only `git push` reaches remote state.
 
 ## Edge Cases
 

package/dist/gaia-ops/skills/subagent-request-approval/SKILL.md

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

package/dist/gaia-ops/skills/subagent-request-approval/reference.md

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

package/dist/gaia-ops/tools/context/README.md

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

package/dist/gaia-ops/tools/gaia_simulator/extractor.py

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

package/dist/gaia-security/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "gaia-security",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
   "author": {
     "name": "jaguilar87",

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

@@ -19,6 +19,7 @@ Provides:
     - parse_rollback_executed(): Parse rollback_executed clause (advisory)
     - parse_context_consumption(): Parse context_consumption clause (advisory)
     - parse_memory_suggestions(): Parse memory_suggestions clause (advisory)
+    - parse_user_facing_summary(): Parse user_facing_summary clause (advisory)
 """
 
 import json
@@ -655,6 +656,23 @@ def parse_memory_suggestions(contract: dict) -> List[str]:
     return [str(item) for item in raw if item is not None]
 
 
+def parse_user_facing_summary(contract: dict) -> Optional[str]:
+    """Parse the optional top-level ``user_facing_summary`` clause (advisory).
+
+    The single human-audience field in the contract: a short prose summary the
+    subagent writes once for the user. The orchestrator relays it near-verbatim
+    on a single-agent COMPLETE (N=1) instead of re-synthesizing ``key_outputs``.
+
+    Strictly additive and advisory -- the validator never rejects based on this
+    field. Returns the trimmed string when present and non-empty, else None.
+    """
+    raw = contract.get("user_facing_summary")
+    if not isinstance(raw, str):
+        return None
+    text = raw.strip()
+    return text or None
+
+
 def extract_plan_status_from_output(agent_output: str) -> str:
     """Extract the effective plan_status string from agent output.