@jaguilar87/gaia 5.0.0-rc.2

package/dist/gaia-ops/skills/memory-search/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: memory-search
+description: Use when searching, inspecting, or diagnosing episodic memory via the `gaia memory` CLI -- queries like "what do I remember about X", "search my memory", "show episode", or memory health checks
+metadata:
+  user-invocable: false
+  type: reference
+---
+
+# Memory Search
+
+Inspect and query Gaia's episodic memory (Memory v2) through the `gaia memory` CLI. Memory v2 indexes past sessions in an FTS5 SQLite database with hybrid scoring (recency + retrieval count). This skill covers search, stats, show, and conflict detection. For curating/reorganizing the separate MEMORY.md index and topic files, load `memory-curation` instead.
+
+## When to use each subcommand
+
+| Trigger | Subcommand |
+|---------|-----------|
+| "what do I know about X", "search my memory" | `gaia memory search <query>` |
+| "memory health", "is my memory healthy" | `gaia memory stats` |
+| "show episode abc123", "open that memory" | `gaia memory show <id>` |
+| "any memory conflicts", "contradictions" | `gaia memory conflicts` |
+
+Always prefer `--json` when the output will feed a follow-up step. Human text is for final user replies.
+
+## Output shapes
+
+All shapes are contract -- downstream code relies on these keys.
+
+```
+gaia memory search "<query>" [--limit N] --json
+  -> {"results": [{"id", "title", "score", "date", "snippet"}]}
+
+gaia memory stats --json
+  -> {"total_episodes", "indexed", "avg_score", "conflicts"}
+
+gaia memory show <episode_id> --json
+  -> {"id", "title", "content", "score", "tags", "retrieval_count", "age_days"}
+  exit 1 if episode not found
+
+gaia memory conflicts [--threshold F] --json
+  -> {"conflicts": [{"file_a", "file_b", "score", "reason"}]}
+```
+
+`score` in search and show is the hybrid score from `tools.memory.scoring.score_memory(days_old, retrieval_count)` -- higher means more relevant. `score` in conflicts is semantic similarity between two memory files (0.0-1.0, higher means more similar/conflicting).
+
+## Typical flows
+
+**Answering "what do I remember about X"**
+
+1. `gaia memory search "X" --limit 5 --json`
+2. If `results` empty: tell the user nothing indexed yet, suggest checking `stats`
+3. If hits: pick top 1-2 by `score`, call `gaia memory show <id> --json` for full content
+4. Summarize `content` back to the user; cite `date` and `id`
+
+**Diagnosing memory health**
+
+1. `gaia memory stats --json`
+2. If `indexed < total_episodes * 0.9`: FTS5 index is stale -- suggest `gaia doctor --fix`
+3. If `conflicts > 0`: run `gaia memory conflicts --json` to show specifics, then hand off to `memory-curation` for resolution
+4. `avg_score` near 0 means scoring module is not loading -- check `gaia doctor`
+
+**Checking before saving a new memory**
+
+1. `gaia memory search "<topic>" --json` to see if the topic already exists
+2. If high-score hit exists: load it with `show`, extend instead of duplicating
+3. If no hit: safe to create a new memory file (handoff to `memory-curation`)
+
+## Interpreting results
+
+- Empty `results` list is not an error -- it means nothing indexed matches. Surface this plainly; do not invent context.
+- Low `score` (< 0.3) hits are likely noise -- mention them only if explicitly asked for broad results.
+- `age_days` from `show` helps decide whether to trust the memory or flag it as potentially stale.
+- A `conflicts` entry with `score > 0.85` is almost certainly a genuine duplicate/contradiction worth resolving.
+
+## Handoffs
+
+| Situation | Next step |
+|-----------|-----------|
+| Conflicts found, user wants cleanup | Load `memory-curation` skill |
+| FTS5 index stale or missing | Run `gaia doctor --fix` |
+| Want to save a new finding | Load `memory-curation` skill |
+| Results enriched and user wants broader research | Delegate to `investigation` skill or WebSearch |
+
+## Anti-patterns
+
+- **Using `search` for verbatim recall** -- FTS5 ranks by relevance, not exact match. If the user needs an exact episode, use `show <id>`.
+- **Ignoring `--json`** -- piping human output into follow-up logic breaks whenever the format tweaks. Ask for JSON at the source.
+- **Calling `conflicts` on every query** -- it scans all memory files and is expensive; run it only on explicit health-check intent or after bulk imports.
+- **Reporting raw `score` to the user** -- users care about what was found, not the number. Translate: high score -> "strong match", low score -> "loose match".

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

@@ -0,0 +1,160 @@
+---
+name: orchestrator-approval
+description: Use when processing APPROVAL_REQUEST with approval_id from a subagent -- enforces showing values before asking for user consent
+metadata:
+  user-invocable: false
+  type: discipline
+---
+
+# Orchestrator Approval
+
+```
+The user approves EXACT VALUES, not summaries.
+Every AskUserQuestion shows the literal command, every option label
+names the specific action. No exceptions. No brevity shortcuts.
+```
+
+## Mental Model
+
+The orchestrator sits between the subagent and the user. The user cannot make an informed decision on information 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. When the orchestrator shortens "git push origin main" to "aplicar cambios", the user is approving blind.
+
+**Scope:** This skill applies when a subagent emits `APPROVAL_REQUEST` with an `approval_id` in its `approval_request`.
+
+## Pre-Flight Checklist
+
+Before calling AskUserQuestion, verify ALL of the following. If any check fails, go back to the agent's `approval_request` and extract the missing field.
+
+1. Does the question text contain the VERBATIM command or file content from `exact_content`? Not summarized, not paraphrased -- the literal string.
+2. Does the question text contain all 5 labeled fields (OPERATION, COMMAND, SCOPE, RISK, ROLLBACK)?
+3. Does the "Approve" option label name the SPECIFIC action (e.g., "Approve -- push 2 commits to origin/main"), not a generic phrase?
+4. Is the command/content complete? No "..." truncation, no "the above changes".
+5. Does the "Approve" option label end with `[P-{nonce_prefix8}]`? The nonce comes from `approval_request.approval_id` (first 8 chars).
+
+## Mandatory Presentation Format
+
+Every AskUserQuestion `question` parameter must contain these 5 labeled fields, extracted from the agent's `approval_request`:
+
+```
+APPROVAL REQUIRED
+
+OPERACION:  {approval_request.operation}
+COMANDO:    {approval_request.exact_content}  <-- verbatim, never paraphrased
+SCOPE:      {approval_request.scope}
+RIESGO:     {approval_request.risk_level} + why
+ROLLBACK:   {approval_request.rollback}
+```
+
+## Option Label Rules
+
+The "Approve" option MUST name the specific action. The PostToolUse hook activates grants by checking for "approve" in the answer value.
+
+- Format: `"Approve -- {specific_action_description} [P-{nonce_prefix8}]"`
+- The action description comes from `approval_request.operation`
+- The nonce comes from `approval_request.approval_id` (first 8 chars)
+
+## Rules
+
+1. **Grant activates through the PostToolUse hook for AskUserQuestion -- not SendMessage.** Resume the subagent via SendMessage with natural language only. The grant is active before SendMessage is sent -- no delay or verification step is needed.
+
+2. **Scope guard -- resume only with the approved command.** The grant is scoped to the exact command that was blocked. When the agent's `approval_request.exact_content` differs in ANY argument from what the orchestrator put in `COMANDO:` -- even one path segment, one flag, one filename -- the grant will miss and the agent will be blocked again. Do NOT send the agent a resume message that instructs it to run a different command. If the operation has genuinely changed, present a new approval.
+
+3. **Fresh presentation every time.** Each hook-blocked APPROVAL_REQUEST requires its own presentation with all mandatory fields. Prior approvals do not carry forward.
+
+4. **`mode` does NOT survive a SendMessage resume.** The `mode` parameter is per-dispatch of the Agent tool. If the original dispatch was `mode: bypassPermissions` and the subagent emitted APPROVAL_REQUEST mid-task, resuming via SendMessage drops the mode -- the resume runs in `default`. CC native will intercept the same Edit/Write/Bash that the original mode was meant to satisfy. Concrete failure observed: bypass-dispatched subagent hit Gaia hook, user approved via AskUserQuestion (grant active), resume via SendMessage -- CC native blocked the same `mv .claude/briefs/...` because the mode was gone. See "Re-dispatch instead of resume" below.
+
+### Re-dispatch instead of resume (when mode was load-bearing)
+
+When the original dispatch relied on `mode: bypassPermissions` or `mode: acceptEdits` to satisfy CC native on `.claude/` writes, and the subagent blocked mid-task, **do not resume with SendMessage**. Instead:
+
+1. Kill the blocked subagent (it already reported APPROVAL_REQUEST or BLOCKED).
+2. Present the approval via AskUserQuestion (same mandatory format) so the Gaia grant activates for the exact command signature.
+3. Dispatch a **fresh** subagent with the same `mode` the original needed.
+4. The fresh prompt enumerates ALL remaining steps and instructs the subagent to execute them in a single turn. Tell it explicitly: "If a hook blocks any step, emit BLOCKED and stop -- do NOT emit APPROVAL_REQUEST mid-task, do NOT split across turns."
+5. The Gaia grant (scoped to the specific blocked command) activates on the approved step; the new dispatch's `mode` satisfies CC native for every other step.
+
+This applies specifically to multi-step bundles on protected paths (mv/rm/mkdir on `.claude/` + Edit/Write on `.claude/project-context/**`). Splitting such a bundle across dispatch + SendMessage resume is the failure mode.
+
+## Traps
+
+| If you're thinking... | The reality is... |
+|---|---|
+| "The subagent already showed the details" | Show them again -- the user needs them at the decision point |
+| "It's a small change, I can summarize" | Size does not change the contract -- show the exact command |
+| "I'll offer to show details if they want" | The user needs the data BEFORE the question, not after |
+| "The option label 'Approve' is enough" | Without the action, the user clicks blind -- label must say WHAT is approved |
+| "'Approve -- aplicar cambios' describes it" | That is a paraphrase in another language -- name the actual operation |
+| "'Approve -- los 3' is clear from context" | Context is not the label -- spell out what "the 3" are |
+| "The command is long, I'll shorten it" | Show it complete -- truncation hides what the user is approving |
+| "Same operation, slightly different path" | Grants match by command signature -- different path = grant miss = immediate re-block |
+| "I'll tell the agent to run a similar rm" | The agent must run the exact command that was approved, or it gets blocked again |
+| "I'll skip the [P-...] suffix, it's cosmetic" | "The hook extracts the nonce from the label — without it, targeted activation fails" |
+| "Original dispatch had bypassPermissions, resume will too" | `mode` is per-dispatch; resume via SendMessage runs in `default` -- CC native re-blocks. Re-dispatch fresh. |
+| "Subagent blocked mid-task, I'll approve then SendMessage" | If the blocker is CC native on `.claude/` writes, approval alone won't help -- resume loses the mode. Re-dispatch fresh with the needed mode. |
+| "Multi-step mv + Edit can be split: dispatch, approve, resume" | Each turn boundary drops the mode. Pack ALL steps in one fresh dispatch after approval. |
+
+For GOOD vs BAD examples, batch flow, and grant mechanics, see `reference.md`.
+
+## Dispatch mode checklist
+
+Before dispatching a subagent, run through this checklist:
+
+**When to pass `mode: acceptEdits`:**
+- Dispatch edits briefs, plans, or evidence files (`.claude/project-context/**`)
+- Dispatch edits skills, agents, or commands (`.claude/skills/**`, `.claude/agents/**`, `.claude/commands/**`)
+- Dispatch writes any file under `.claude/` that is NOT hooks/ or settings files
+
+**When NOT to use `acceptEdits`:**
+- Dispatch requires mutative Bash (acceptEdits does not cover Bash -- Gaia T3 flow still fires)
+- Dispatch is exploratory/read-only (use `default` or omit mode)
+- Dispatch touches `.claude/hooks/` or `settings.json` -- Gaia blocks these regardless of mode
+
+**foreground vs background:**
+- **foreground**: can call AskUserQuestion; T3 approval flows work end-to-end
+- **background**: AskUserQuestion does not display; T3 operations that require user consent will stall or be auto-denied -- dispatch only read or pre-approved operations to background agents
+
+**The mode is not inherited.** If you run with `acceptEdits`, your subagents still receive `default` unless you pass `mode: acceptEdits` explicitly in the dispatch. Set it per dispatch, not once per session.
+
+| Dispatch type | mode to pass | session |
+|--------------|-------------|---------|
+| Reads only (investigate, report) | omit (default) | foreground or background |
+| Edits `.claude/skills/`, briefs, evidence | `acceptEdits` | foreground or background |
+| T3 requiring user approval | `default` or `acceptEdits` | **foreground only** |
+| Edits `.claude/hooks/` or settings | never dispatch directly | n/a -- requires Gaia approval flow |
+
+## Dispatch mode decision -- checklist pre-dispatch
+
+Antes de cada dispatch del Agent tool, recorre este árbol. Si algún paso produce ambigüedad, detente y pregunta al usuario.
+
+**1. ¿El goal es read-only o escribe?**
+- Read-only → `default` (o `acceptEdits` si necesita escribir evidence)
+- Escribe → paso 2
+
+**2. ¿Dónde escribe?**
+- Solo archivos declarativos (`.md`, `.yaml`, `.json` bajo `.claude/` o `gaia-ops-dev/`) → `acceptEdits`
+- Código runtime (`.py` bajo `hooks/`, `bin/`, `agents/`) → `acceptEdits` + aceptar grants Bash file-scoped esperados
+- Paths protegidos (`.git`, `.vscode`, `.husky`, `.claude/hooks/`, `settings.json`) → `default` + prompt explícito; nunca bypass
+
+**3. ¿Requiere Bash mutativo (mv, rm, mkdir)?**
+- Atómico, scope enumerado, user-approved conceptualmente, hooks hardened → `bypassPermissions`
+- Multi-step / multi-file PURO Edit/Write (sin Bash mutativo) → `acceptEdits` (acepta fricción file-scoped; NO bypass: pierde audit per-file porque background pre-aprueba el bundle entero)
+- Bundle mixto: Bash mutativo (mv/rm) SOBRE `.claude/` + Edits SOBRE `.claude/` → `bypassPermissions` + foreground + **empaquetar todos los steps en un solo turno** (ver Rule 4 y "Re-dispatch instead of resume" arriba). `acceptEdits` no alcanza porque no cubre el mv; split en turnos pierde el mode en el SendMessage resume.
+
+**4. ¿Puede emitir `approval_request` mid-task?**
+- Sí (scope puede evolucionar, T3 esperados) → foreground
+- No (scope cerrado, permisos pre-satisfechos) → background + mode que pre-satisfaga permisos
+
+**5. ¿El goal enumera el scope concreto?**
+- No → DETÉN y pregunta al usuario antes del dispatch. No elegir mode sobre scope vago.
+- Sí → continúa con la combinación decidida.
+
+Cross-reference: para qué hace cada mode, ver `skills/security-tiers/SKILL.md` → "permissionMode comparison" y "Decision tree".
+
+### Ejemplos concretos
+
+| Goal | mode | session | Razón |
+|------|------|---------|-------|
+| Editar brief.md o plan.md | `acceptEdits` | background | Declarativo, scope cerrado, no requiere prompts mid-task |
+| Mover directorio de brief al cerrar (`open_X` → `closed_X`) | `bypassPermissions` | foreground | Atómico, scope aprobado, hardened bash_validator; foreground porque puede descubrir conflicto de nombre |
+| Split de enum en 3 archivos Python runtime | `acceptEdits` | background | Grants file-scoped esperados per-file -- fricción intencional para audit |
+| Bulk reject de pendings via CLI | `acceptEdits` | foreground | CLI maneja inline; foreground por si requiere confirmación mid-loop |
+| Investigation read-only con evidence write | `default` al leer, `acceptEdits` al escribir evidence | foreground | Dos dispatches distintos con modes distintos; no heredar entre ellos |

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

@@ -0,0 +1,174 @@
+# Orchestrator Approval -- Reference
+
+Detailed templates, examples, and batch flow. Read on-demand when presenting approvals.
+
+## GOOD vs BAD Examples
+
+### Example 1: Git push
+
+**BAD -- vague label, missing fields:**
+```
+AskUserQuestion(
+  question="Shall I push the changes?",
+  options=["Approve", "Reject"]
+)
+```
+Missing: OPERATION, COMMAND, SCOPE, RISK, ROLLBACK. Label "Approve" does not name the action.
+
+**BAD -- paraphrased command, generic label:**
+```
+AskUserQuestion(
+  question="APPROVAL REQUIRED\n\nOPERACION: Push changes\nCOMANDO: push the 2 commits\nSCOPE: main branch\nRIESGO: MEDIUM\nROLLBACK: git revert",
+  options=["Approve -- aplicar cambios", "Reject"]
+)
+```
+COMMAND is paraphrased ("push the 2 commits" instead of the literal `git push origin main`). Label is vague Spanish.
+
+**GOOD -- verbatim command, specific label:**
+```
+AskUserQuestion(
+  question=(
+    "APPROVAL REQUIRED\n\n"
+    "OPERACION: Push 2 commits to origin/main\n"
+    "COMANDO:   git push origin main\n"
+    "SCOPE:     remote origin, branch main -- 2 commits (a1b2c3, d4e5f6)\n"
+    "RIESGO:    MEDIUM -- modifies shared branch history\n"
+    "ROLLBACK:  git revert a1b2c3..d4e5f6"
+  ),
+  options=["Approve -- push 2 commits to origin/main [P-a1b2c3d4]", "Modify", "Reject"]
+)
+```
+
+### Example 2: Terraform apply
+
+**BAD:**
+```
+options=["Approve -- los 3 recursos", "Reject"]
+```
+"los 3 recursos" -- what 3? The user cannot tell from the label alone.
+
+**GOOD:**
+```
+AskUserQuestion(
+  question=(
+    "APPROVAL REQUIRED\n\n"
+    "OPERACION: Apply Terraform changes to dev VPC\n"
+    "COMANDO:   terraform -chdir=/infra/dev apply -auto-approve\n"
+    "SCOPE:     3 resources: google_compute_network.dev, google_compute_subnetwork.dev-a, google_compute_subnetwork.dev-b\n"
+    "RIESGO:    MEDIUM -- creates new cloud resources in dev\n"
+    "ROLLBACK:  terraform -chdir=/infra/dev destroy -auto-approve"
+  ),
+  options=["Approve -- terraform apply (3 resources in dev) [P-9c4e1f2a]", "Modify", "Reject"]
+)
+```
+
+### Example 3: Multiple file edits
+
+**BAD:**
+```
+options=["Approve -- aplicar cambios", "Reject"]
+question="Can I make the changes we discussed?"
+```
+
+**GOOD:**
+```
+AskUserQuestion(
+  question=(
+    "APPROVAL REQUIRED\n\n"
+    "OPERACION: Edit 3 config files to update API endpoint\n"
+    "COMANDO:\n"
+    "  1. Edit /app/config/prod.yaml -- api_url: https://old.api.com -> https://new.api.com\n"
+    "  2. Edit /app/config/staging.yaml -- api_url: https://old.api.com -> https://new.api.com\n"
+    "  3. Edit /app/.env.production -- API_BASE=https://old.api.com -> API_BASE=https://new.api.com\n"
+    "SCOPE:     3 config files in /app/config/ and /app/.env.production\n"
+    "RIESGO:    HIGH -- production config, affects live API routing\n"
+    "ROLLBACK:  git checkout HEAD -- /app/config/prod.yaml /app/config/staging.yaml /app/.env.production"
+  ),
+  options=["Approve -- update API endpoint in 3 config files [P-d7f3a09b]", "Modify", "Reject"]
+)
+```
+
+## Option Label Patterns
+
+| Pattern | Verdict | Why |
+|---------|---------|-----|
+| `"Approve -- push 2 commits to origin/main [P-a1b2c3d4]"` | GOOD | Names exact action, includes nonce suffix |
+| `"Approve -- terraform apply (3 resources in dev) [P-9c4e1f2a]"` | GOOD | Names tool, count, environment, includes nonce suffix |
+| `"Approve -- delete branch feature/old-login [P-f5b0e871]"` | GOOD | Names the destructive action and target, includes nonce suffix |
+| `"Approve -- push 2 commits to origin/main"` | BAD | Missing `[P-{8hex}]` suffix -- hook cannot do targeted activation |
+| `"Approve"` | BAD | No action description |
+| `"Approve -- aplicar cambios"` | BAD | Vague paraphrase |
+| `"Approve -- los 3"` | BAD | What 3? |
+| `"Approve -- proceed"` | BAD | "proceed" adds no information |
+| `"Approve -- the plan above"` | BAD | References context, not action |
+| `"Si, ejecutar"` | BROKEN | Missing "Approve" -- hook will not activate grant |
+
+## Batch Approval Flow
+
+When `approval_request` contains `batch_scope: "verb_family"`, the agent requests a
+multi-use grant covering many commands with the same base CLI and verb but different arguments.
+
+**Presentation:** Use the same mandatory format, but frame the scope as a batch:
+- OPERACION describes the batch (e.g., "Modify 500 Gmail messages")
+- COMANDO shows the command pattern (e.g., "`gws gmail users messages modify`")
+- SCOPE states the TTL (e.g., "All modify operations for the next 10 minutes")
+
+**Options:** `["Approve batch -- modify 500 Gmail messages [P-{nonce_prefix8}]", "Approve single -- {first_command} [P-{nonce_prefix8}]", "Modify", "Reject"]`
+- "Approve batch" creates a verb-family grant (multi-use, 10-minute TTL)
+- "Approve single" creates a normal single-use grant for only the first blocked command
+
+**CRITICAL -- "batch" in the label:** The word "batch" MUST appear in the Approve option label for verb-family grants to activate. The PostToolUse hook checks the label text to decide whether to create a verb-family (multi-use) grant or a single-use grant. Without "batch" in the label, the hook creates a single-use grant and every command after the first one gets blocked again.
+
+**BAD -- missing "batch" keyword:**
+```
+options=["Approve -- modify 500 Gmail messages [P-a1b2c3d4]", "Reject"]
+```
+Result: single-use grant created. First `gws gmail users messages modify` succeeds. Second one is blocked. Agent enters re-block loop for remaining 499 messages.
+
+**GOOD -- "batch" keyword present:**
+```
+options=["Approve batch -- modify 500 Gmail messages [P-a1b2c3d4]", "Reject"]
+```
+Result: verb-family grant created (multi-use, 10-minute TTL). All 500 `gws gmail users messages modify` commands pass through.
+
+**Resume:** After batch approval, resume via SendMessage with: "Batch approved. Proceed with all [verb] operations."
+
+## Grant Activation Mechanics
+
+When a hook blocks a T3 command, it writes a pending approval and returns an `approval_id` in the deny response. The subagent includes this `approval_id` in its `approval_request`. The orchestrator presents the plan via AskUserQuestion with structured options. When the user selects an "Approve" option, the PostToolUse hook for AskUserQuestion fires and activates the pending grant. No nonce or approval_id is relayed through SendMessage -- grant activation is handled entirely by the hook.
+
+**Timing:** Grant activation is synchronous. The PostToolUse hook runs before AskUserQuestion returns to the orchestrator. By the time the orchestrator is ready to send SendMessage, the grant is already active. There is no race condition and no delay is needed.
+
+## Scope Mismatch -- The Common Re-block Trap
+
+Grants are matched by **semantic signature**: `base_cmd + verb + normalized arguments`. Two commands with the same verb but different path arguments are different signatures and do NOT share a grant.
+
+**Example of the trap:**
+
+1. Agent is blocked trying to run:
+   `rm /path/to/approvals/grant-default-1776179289490.json`
+
+2. Orchestrator approves it. The grant is scoped to that exact command.
+
+3. Orchestrator sends resume: "Delete the stale grant file and then do the git operations"
+
+4. Agent decides to run:
+   `rm /path/to/approvals/grant-session-1776179452326.json`
+   (different filename, same directory)
+
+5. **Blocked again** -- the grant scope does not cover the new path.
+
+**Why it happens:** The orchestrator paraphrased the operation ("delete the stale grant file") instead of quoting the approved command verbatim. The agent had latitude to choose a different target.
+
+**Correct resume message:** Quote the exact approved command in the resume.
+
+```
+# BAD resume
+"Proceed. Delete the stale grant file and then do the git operations."
+
+# GOOD resume
+"Proceed. Run exactly: rm /path/to/approvals/grant-default-1776179289490.json"
+"Then continue with the git operations."
+```
+
+If the correct target has changed since the approval (e.g., the file that was blocked no longer exists and a different file needs to be deleted), present a new approval for the new command -- do not resume with modified instructions.

package/dist/gaia-ops/skills/pending-approvals/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: pending-approvals
+description: Use when there are pending approval requests to present — "aprobar", "ver pendientes", "approve P-", "reject P-"
+metadata:
+  user-invocable: true
+  type: technique
+---
+
+# Pending Approvals
+
+## When SessionStart injects pending approvals
+
+1. Present the summary to the user (already formatted by the scanner)
+2. Wait for user to say "ver P-XXXX" or "aprobar P-XXXX"
+
+The scanner formats each entry as:
+```
+P-{nonce_prefix8}  {command}  [{danger_verb}]  {age}
+```
+
+## When user says "ver P-XXXX"
+
+1. Find the pending file whose nonce starts with the given prefix
+2. Present full details: operation, exact command (verbatim), context, risk, rollback
+3. Ask: "aprobar" or "rechazar"
+
+## When user says "aprobar P-XXXX"
+
+1. Find the pending file whose nonce starts with the given prefix
+2. Call AskUserQuestion with ALL mandatory fields visible:
+
+```
+APPROVAL REQUIRED
+
+OPERATION: {danger_verb} on {base_cmd}
+COMMAND:   {command}  ← verbatim, no paraphrase
+SCOPE:     {scope from context field}
+RISK:      {danger_category}
+ROLLBACK:  {rollback from context field}
+```
+
+3. AskUserQuestion options: `["Approve -- {specific_action} [P-{nonce_prefix8}]", "Reject"]`
+   - Label MUST start with "Approve" (PostToolUse grant activation checks for "approve")
+   - Label MUST end with `[P-{nonce_prefix8}]` (PostToolUse hook extracts nonce from label for targeted activation)
+   - Label MUST name the specific action (e.g., "Approve -- kubectl apply -f manifest.yaml [P-8072af80]")
+   - NEVER use vague labels like "Approve -- aplicar cambios" or "Approve -- proceed"
+4a. Cross-session check: if `pending.session_id` != current `CLAUDE_SESSION_ID`:
+    - The nonce is stale (from a prior session) -- do NOT pass it to the agent
+    - The PostToolUse hook will have already activated the grant under the current session
+    - Dispatch a one-shot agent using the dispatch template from `reference.md` (command + cwd + preflight + recovery instructions, no nonce)
+    - The hook will find the pre-activated grant and allow the T3 operation through
+4b. Same-session: dispatch a one-shot agent using the dispatch template from `reference.md` (command + cwd + nonce + preflight + recovery instructions)
+5. On Reject: call `reject_pending(nonce_prefix)` to mark the pending as rejected; confirm to user
+
+## When user says "rechazar P-XXXX"
+
+1. The orchestrator dispatches an agent to edit the pending JSON file at `.claude/cache/approvals/pending-{nonce}.json`, setting `"status": "rejected"` and `"rejected_at"` to the current timestamp
+2. Do NOT use `rm` to delete the file -- that triggers T3 approval. The `reject_pending()` function in `approval_grants.py` handles this via file I/O (read JSON, modify, write back)
+3. The pending scanner will clean up rejected files on its next sweep
+4. Confirm: "P-XXXX rechazado"
+
+## Anti-patterns
+
+- Approving without showing the exact command — user needs to see verbatim, not a summary
+- Summarizing command as "the deploy" or "the apply" instead of showing the literal string
+- Asking for approval without AskUserQuestion — the PostToolUse grant hook will not activate
+- Prefixing the approve option with anything other than "Approve" (e.g. "Sí, ejecutar")
+- Dispatching execution before AskUserQuestion confirms approval
+- Omitting the `[P-{nonce_prefix8}]` suffix from the Approve label — the hook cannot do targeted activation without it
+- Fire-and-forget dispatch -- omitting preflight checks and recovery instructions from the dispatch prompt
+
+For JSON schema, format templates, flow example, and dispatch template: read `reference.md`.