@jaguilar87/gaia 5.0.7 → 5.0.9

package/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,19 +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.** The hook mints the `approval_id` at SubagentStop (`_intake_command_set_pending` -- see Rule 3); the subagent emits the `command_set` with **no** `approval_id`. So you do not have an agent-reported id to trust even if you wanted to -- you ALWAYS recover the freshly minted id from `gaia approvals pending` for the current session. This is the general shape made unavoidable: the DB mints, the orchestrator recovers, the agent never owns the id.
+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
 
@@ -66,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
 
@@ -84,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
@@ -120,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 always recover it from the DB. |
+| "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/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/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,19 +27,21 @@ 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.
 
-## No batch template
+## Batch template (COMMAND_SET)
 
-There is no batch/multi-use approval in the current code. The `verb_family` grant
-was removed (see the module docstring of
-`hooks/modules/security/approval_grants.py`) and the `COMMAND_SET` replacement
-has no production activation path (`create_command_set_grant` has no production
-caller). The word "batch" in a label and a `batch_scope` field are both ignored.
-For a sweep of N commands, present each command with its own single-command
-approval (the template above), once per `approval_id`. See `reference.md` ->
-"On batch intents".
+When the subagent emits a plan-first `APPROVAL_REQUEST` with a `command_set`
+of >= 2 `{command, rationale}` items and **no** `approval_id`, the
+SubagentStop intake mints ONE pending `COMMAND_SET` approval. Present it as
+a single approval: list all N commands in the question body, one Approve
+label with one `[P-{nonce8}]` suffix. See `reference.md` -> "On batch
+intents" for the full layout.
+
+A `batch_scope` field and the word "batch" in an option label are both
+ignored -- the signal is the presence of `command_set` in the contract.
 
 ## Field Extraction Reference
 
@@ -46,4 +52,4 @@ approval (the template above), once per `approval_id`. See `reference.md` ->
 | 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) |

package/skills/pending-approvals/SKILL.md

@@ -37,7 +37,7 @@ report "rejected" when nothing actually changed.
 | `gaia approvals list` | DB grants + filesystem pendings | `cmd_list` (mixed) |
 | `gaia approvals reject NONCE` | filesystem only | `reject_pending` in `hooks/modules/security/approval_grants.py` |
 | `gaia approvals reject-all` | filesystem only | loops `reject_pending` |
-| `gaia approvals clean` | filesystem only | `cleanup_expired_grants` |
+| `gaia approvals clean` | DB (cross-session stale pendings) + filesystem | `cmd_clean` in `bin/cli/approvals.py`: calls `store.list_pending(all_sessions=True)`, transitions every pending older than `DEFAULT_PENDING_TTL_MINUTES` (24 h) to `revoked` via `store.revoke()`, then calls `cleanup_expired_grants` for filesystem files |
 
 The practical consequence: `revoke` is the DB-aware single-id verb; `reject` and
 `reject-all` only touch the legacy filesystem queue. If you need to mark a DB
@@ -105,15 +105,19 @@ Offer bulk cleanup when the user says "limpia todos los pendings", "borra los
 pendientes", or when SessionStart surfaces 5+ orphaned pendings the user has
 not engaged with.
 
-- `gaia approvals reject-all` -- bulk reject across the **filesystem** queue.
-  Returns "0 rejected" when the queue is empty.
-- `gaia approvals clean` -- removes expired/stale **filesystem** files.
+- `gaia approvals reject-all` -- bulk soft-reject across the **filesystem** queue.
+  Returns "0 rejected" when the queue is empty. Does not touch DB rows.
+- `gaia approvals clean` -- the first-class cross-session bulk drain for stale
+  DB pendings: `cmd_clean` calls `store.list_pending(all_sessions=True)` and
+  transitions every pending older than 24 h (`DEFAULT_PENDING_TTL_MINUTES`) to
+  `revoked` via `store.revoke()`, then runs `cleanup_expired_grants` to clean
+  expired filesystem grant files. Runs without a T3 prompt (consent-reducing,
+  listed in `CONSENT_REDUCING_SUBCOMMAND_EXCEPTIONS`). Use this when
+  `gaia approvals pending --all-sessions` shows a backlog of stale rows.
 
-There is no first-class bulk-revoke for the DB queue. If `gaia approvals
-pending --all-sessions` shows rows that need clearing, either revoke each by id
-or call `store.revoke()` in a short Python loop. Do not report "bulk cleanup
-done" after `reject-all` if the DB queue still has pending rows -- check
-`gaia approvals pending --all-sessions` to confirm.
+Do not report "bulk cleanup done" after `reject-all` alone -- it only clears
+the filesystem queue. Run `gaia approvals clean` to drain the DB backlog, then
+confirm with `gaia approvals pending --all-sessions`.
 
 Do not offer `reject-all` when there are active same-session pendings the user
 may still want to approve.
@@ -123,8 +127,9 @@ may still want to approve.
 - Approving without showing the exact COMANDO -- the user consents on the
   verbatim string, not a summary. The full presentation discipline lives in
   `orchestrator-present-approval`; this skill does not restate it.
-- Treating `gaia approvals reject-all` as a DB cleanup -- it operates on the
-  filesystem queue only. DB rows survive the call.
+- Treating `gaia approvals reject-all` as a full cleanup -- it operates on the
+  filesystem queue only; DB rows survive the call. Use `gaia approvals clean`
+  to drain the DB backlog.
 - Reporting "rechazado" without verifying the store -- `revoke` returns
   `not_found` for filesystem-only pendings; the inverse happens for `reject` on
   DB rows. Pick the verb by store, or be ready to fall back.

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

@@ -44,9 +44,20 @@ Add an `approval_request` to your `agent_contract_handoff`, copying the hook's f
 
 The `approval_request` schema is canonical in `agent-approval-protocol` — relay the sealed_payload fields verbatim (the hook built them) and add `verification` (your own success criteria) + `approval_id` (the literal token from the denial). See `agent-approval-protocol/SKILL.md` for the full field list and types.
 
-The `approval_id` is the `P-{...}` token the orchestrator uses to find the
-`REQUESTED` row in the DB and validate the fingerprint. Fields written only in
-prose are invisible to the presentation -- the user would approve blind.
+The `approval_id` is the `P-{...}` token tying this request to its `REQUESTED`
+row in the DB. Fields written only in prose are invisible to the presentation --
+the user would approve blind.
+
+**What your relay is for: same-turn immediacy.** Your `approval_request` is the
+orchestrator's source only for the CURRENT turn. The orchestrator's primary
+source is the per-turn `[PENDING-APPROVALS-VERIFIED]` block injected at
+`UserPromptSubmit`, which carries every pending that has survived >= 1 turn,
+already DB-read and fingerprint-verified. But that block was built before you
+ran this turn, so a pending you mint now is not in it yet -- the orchestrator
+presents it from your relay until the next turn's block picks it up. You emit the
+same fields either way; nothing on your side changes. The orchestrator never
+dispatches a subagent to verify or derive your request -- integrity is enforced
+at grant activation, not at presentation.
 
 ## Non-negotiable rules
 
@@ -99,6 +110,20 @@ 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).
 
+You still emit the `command_set` with **no `approval_id`** -- nothing changes on
+your side. What changed underneath: the minted `approval_id` is now
+**content-derived** from the command_set
+(`derive_command_set_id` -> `P-<first 32 hex of sha256(canonical commands)>`),
+not a random uuid4. You do not compute or emit it (you cannot hash reliably, and
+you have nothing to attempt yet); the value is purely internal. The reason it
+matters: the content-derived id is reproducible without a uuid4 that could be
+lost across sessions. Once the minted pending has survived a turn, the
+orchestrator reads it -- with all N commands -- straight from the injected
+`[PENDING-APPROVALS-VERIFIED]` block (no DB search, no derive-dispatch); for the
+turn you mint it in, the orchestrator presents from the `command_set` in your
+relay. Your contract stays the same -- `command_set` of `{command, rationale}`
+items, no `approval_id`.
+
 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

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

@@ -16,8 +16,12 @@ payload from the intercepted command and calls
 3. writes the `REQUESTED` event to the DB.
 
 The block message you receive (`[T3_BLOCKED] ...`) ends with `approval_id: P-{...}`.
-You relay that token plus the operation details; the orchestrator re-derives the
-fingerprint from the DB row.
+You relay that token plus the operation details. For the current turn the
+orchestrator presents from your relay; once the pending survives a turn it
+appears in the per-turn `[PENDING-APPROVALS-VERIFIED]` block, already
+fingerprint-verified by the hook. Payload integrity is enforced at grant
+activation (`verify_fingerprint`), so the orchestrator never dispatches to
+verify or derive your request.
 
 Source: `bash_validator._build_sealed_payload()`, the subagent block path in
 `bash_validator._validate_single_command()`; `gaia/approvals/store.py`
@@ -94,6 +98,24 @@ 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.
 
+**The COMMAND_SET `approval_id` is content-derived, not uuid4.** Unlike the
+singular hook-block path (which mints `P-{uuid4hex}`), the intake derives the id
+from the command_set content via `gaia.approvals.store.derive_command_set_id()`:
+`P-<first 32 hex of sha256(canonical(post-filter command strings))>`. It then
+passes that id to `insert_requested(..., approval_id=...)` as the pending row id.
+The point is reproducibility without a fragile uuid4: a uuid4 minted at
+SubagentStop could not be recovered by the parent (Claude Code #5812), but a
+content-derived id needs no recovery -- the same canonicalization
+(`chain.canonical_payload`) and mutative filter always yield the same id. Once
+the minted pending survives a turn, the orchestrator reads that id (and all N
+commands) straight from the injected `[PENDING-APPROVALS-VERIFIED]` block -- no
+DB lookup and no `gaia approvals derive-id` dispatch; for the mint turn it
+presents from the `command_set` in your relay. The id is
+**order-sensitive** (the consume side matches positionally) and **content-only**
+(rationale/session/agent are not folded in, so both sides agree from the command
+list alone). Idempotency follows the existing fingerprint dedup: two identical
+command sets map to one id.
+
 **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:
@@ -138,13 +160,17 @@ single-use within the 60-minute window.
 Always `plan_status: "APPROVAL_REQUEST"`. The presence of `approval_id` tells the
 orchestrator which path:
 
-- **With `approval_id`** -- the hook blocked a single command; orchestrator
-  validates the fingerprint and activates the single-use semantic grant on user
-  approval.
+- **With `approval_id`** -- the hook blocked a single command; the orchestrator
+  presents from your relay (current turn) or the injected
+  `[PENDING-APPROVALS-VERIFIED]` block (later turns), and the single-use semantic
+  grant activates on user approval (fingerprint checked at activation).
 - **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.
+  batch. The SubagentStop intake processor mints ONE pending `COMMAND_SET` with a
+  **content-derived** id (`derive_command_set_id`). The orchestrator reads that
+  id and the N commands from the injected `[PENDING-APPROVALS-VERIFIED]` block
+  (no derive-dispatch), or, for the mint turn, from the `command_set` in your
+  relay, then presents the single approval (N commands, one nonce). 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.

package/tools/migration/README.md

@@ -19,7 +19,12 @@ desde el filesystem hacia `~/.gaia/gaia.db`.
 | 01 | Episodes | `.claude/project-context/episodic-memory/episodes.jsonl` | `episodes` (+`episodes_fts`) |
 | 02 | Memory | `~/.claude/projects/-home-jorge-ws-me/memory/*.md` | `memory` (+`memory_fts`) |
 | 03 | Context contracts | `.claude/project-context/project-context.json` | `context_contracts` |
-| 04 | Harness events | `.claude/events/events.jsonl` | `harness_events` |
+| 04 | Harness events | ~~`.claude/events/events.jsonl`~~ (ELIMINADO) | `harness_events` |
+
+> **Dominio 04 completado y eliminado.** `events.jsonl` y su archivo `.lock` fueron
+> retirados. El hook `event_writer` escribe directamente a `harness_events` en la DB.
+> El script `migrate_04_harness_events.py` y su wrapper `.sh` fueron borrados una vez
+> completada la absorción. Los datos vivos se leen desde `harness_events` en `~/.gaia/gaia.db`.
 
 Cada dominio tiene 2 archivos:
 
@@ -37,8 +42,8 @@ bootstrap.sh                             # crea/inicializa ~/.gaia/gaia.db con s
 ./migrate_01_episodes.sh                 # ~50-80 MB de SQL, batch 80
 ./migrate_02_memory.sh                   # 28 .md (MEMORY.md excluido)
 ./migrate_03_context_contracts.sh        # 12 secciones
-./migrate_04_harness_events.sh           # ~5-10 MB de SQL, batch 200
-./validate.sh                            # 5 aserciones read-only
+# migrate_04_harness_events.sh ELIMINADO — dominio 04 completado; eventos en DB-canonical
+./validate.sh                            # aserciones read-only (V4 eliminada junto con 04)
 ```
 
 Cada script imprime `[migrate_NN] OK` al terminar.
@@ -50,14 +55,7 @@ Cada script imprime `[migrate_NN] OK` al terminar.
 | 01 episodes | `INSERT OR IGNORE` (PK = `episode_id`) | sí |
 | 02 memory | `INSERT OR IGNORE` (PK = `(project, name)`) | sí |
 | 03 context_contracts | `INSERT OR IGNORE` (PK = `(project, section_name)`) | sí |
-| 04 harness_events | `INSERT` simple (sin PK natural) | **no — duplica filas** |
-
-Para re-ejecutar 04 limpiamente:
-
-```
-sqlite3 ~/.gaia/gaia.db "DELETE FROM harness_events WHERE project='me';"
-./migrate_04_harness_events.sh
-```
+| 04 harness_events | N/A — tool eliminado; escritura vía `event_writer` DB-direct | N/A |
 
 ## Validación
 
@@ -68,7 +66,7 @@ sqlite3 ~/.gaia/gaia.db "DELETE FROM harness_events WHERE project='me';"
 | V1 | `COUNT(*) FROM episodes` == líneas no vacías de `episodes.jsonl` |
 | V2 | `COUNT(*) FROM memory` == archivos `.md` (excluyendo `MEMORY.md`) |
 | V3 | `COUNT(*) FROM context_contracts` == 12 |
-| V4 | `COUNT(*) FROM harness_events` == líneas no vacías de `events.jsonl` |
+| ~~V4~~ | ~~`COUNT(*) FROM harness_events` == líneas no vacías de `events.jsonl`~~ — eliminado junto con el dominio 04 |
 | V5 | `COUNT(*) FROM episodes_fts` == `COUNT(*) FROM episodes` (FTS sync) |
 
 Exit code: 0 si todas pasan, 1 si alguna falla.