@jaguilar87/gaia 5.0.6 → 5.0.8

package/skills/gaia-patterns/reference.md

@@ -80,14 +80,6 @@ SessionStart emits a one-shot `hookSpecificOutput.additionalContext` manifest (E
 | `skill-creation/` | Technique | Injected (gaia-system) |
 | `skills/reference.md` | Reference | On-demand (shared security-tiers ref) |
 
-### Commands (slash commands)
-
-| Command | File | Purpose |
-|---------|------|---------|
-| `/gaia` | `commands/gaia.md` | Invoke gaia meta-agent |
-| `/scan-project` | `commands/scan-project.md` | Scan project, update project context in ~/.gaia/gaia.db |
-| `/gaia-plan` | `commands/gaia-plan.md` | Plan a feature, create brief, decompose into tasks |
-
 ### Tools (7 subsystems)
 
 | Subsystem | Location | Purpose |
@@ -139,7 +131,7 @@ The package ships a single `gaia` binary (`bin/gaia.js`) that dispatches to Pyth
 
 | Mode | Package | What ships |
 |------|---------|-----------|
-| `gaia-ops` | `@jaguilar87/gaia` (full) | All hooks, all modules, all agents, all skills, all commands, all tools, all config |
+| `gaia-ops` | `@jaguilar87/gaia` (full) | All hooks, all modules, all agents, all skills, all tools, all config |
 | `gaia-security` | `@jaguilar87/gaia` (security dist) | 6 hooks (`pre_tool_use`, `post_tool_use`, `stop_hook`, `user_prompt_submit`, `session_start`, `session_end_hook`), all modules, no agents, no skills, no config |
 
 ### Detection Cascade (`hooks/modules/core/plugin_mode.py`)
@@ -159,7 +151,6 @@ The package ships a single `gaia` binary (`bin/gaia.js`) that dispatches to Pyth
 | T3 approval | Claude Code native dialog (`permissionDecision: ask`) | Hook blocks with nonce, orchestrator approval flow |
 | Agents | None | 8 agents routed by orchestrator |
 | Skills | None | 24 skills injected per frontmatter |
-| Commands | None | 7 slash commands |
 | PreToolUse matchers | `Bash` only | `Bash`, `Task`, `Agent`, `SendMessage`, multi-tool |
 | File write protection | `_is_protected()` blocks hooks/ and settings*.json for Edit/Write tools | Same -- fires regardless of permissionMode |
 
@@ -206,7 +197,7 @@ npm publish                    # publishes @jaguilar87/gaia
 3. Run `scripts/bootstrap_database.sh` -- seeds the schema (v17), agent rows, and `schema_version`. Fail-loud: any non-zero exit writes `~/.gaia/last-install-error.json` and propagates the error.
 4. Merge permissions, env vars, and agent key into `settings.local.json` (preserves user config).
 5. Merge hooks from `hooks.json` into `settings.local.json` via the consolidated `merge_hooks` step.
-6. Create `.claude/{agents, tools, hooks, commands, templates, config, skills}` symlinks (7) plus `CHANGELOG.md` file link.
+6. Create `.claude/{agents, tools, hooks, config, skills}` symlinks (5) plus `CHANGELOG.md` file link.
 7. Write `plugin-registry.json` with `installed[].name == "gaia-ops"` (or `gaia-security`).
 8. Verification.
 
@@ -229,8 +220,6 @@ The hook invoker is `python3 <script>` rather than executing the script directly
 .claude/agents    -> node_modules/@jaguilar87/gaia/agents/
 .claude/tools     -> node_modules/@jaguilar87/gaia/tools/
 .claude/hooks     -> node_modules/@jaguilar87/gaia/hooks/
-.claude/commands  -> node_modules/@jaguilar87/gaia/commands/
-.claude/templates -> node_modules/@jaguilar87/gaia/templates/
 .claude/config    -> node_modules/@jaguilar87/gaia/config/
 .claude/skills    -> node_modules/@jaguilar87/gaia/skills/
 .claude/CHANGELOG.md (file link) -> node_modules/@jaguilar87/gaia/CHANGELOG.md
@@ -333,7 +322,6 @@ ln -sf /home/jorge/ws/me/gaia-dev/agents   .claude/agents
 ln -sf /home/jorge/ws/me/gaia-dev/hooks    .claude/hooks
 ln -sf /home/jorge/ws/me/gaia-dev/skills   .claude/skills
 ln -sf /home/jorge/ws/me/gaia-dev/tools    .claude/tools
-ln -sf /home/jorge/ws/me/gaia-dev/commands .claude/commands
 ln -sf /home/jorge/ws/me/gaia-dev/config   .claude/config
 ```
 

package/skills/orchestrator-present-approval/SKILL.md

@@ -39,7 +39,13 @@ 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.
+**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.
 
 ## Mandatory presentation -- 5 labeled fields + nonce-suffixed label
 
@@ -121,4 +127,4 @@ wording, see `reference.md` -> "GOOD vs BAD Examples", "Option Label Patterns",
 | "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. |
+| **"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. |

package/skills/orchestrator-present-approval/template.md

@@ -26,16 +26,17 @@ 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).
 
-## No batch template
-
-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".
+## Batch template (COMMAND_SET)
+
+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
 

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

@@ -99,6 +99,17 @@ 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 orchestrator reproduces that exact id from the `command_set` you
+emitted (via `gaia approvals derive-id`), with no DB search and no cross-session
+miss. 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

@@ -94,6 +94,22 @@ 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 DB lookup: the orchestrator holds the
+same `command_set` (you emitted it in the contract) and reproduces the EXACT id
+with `gaia approvals derive-id`, which applies the same mutative filter and the
+same canonicalization (`chain.canonical_payload`). This closes the cross-session
+miss -- a uuid4 minted at SubagentStop could not be recovered by the parent
+(Claude Code #5812), but a content-derived id needs no recovery. 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:
@@ -142,9 +158,11 @@ orchestrator which path:
   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.
+  batch. The SubagentStop intake processor mints ONE pending `COMMAND_SET` with a
+  **content-derived** id (`derive_command_set_id`), and the orchestrator
+  reproduces that exact id from the command_set via `gaia approvals derive-id`
+  (no DB search) before presenting 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/gaia/approvals/revert.py

@@ -1,282 +0,0 @@
-"""gaia.approvals.revert -- Inverse-command derivation for approval revert.
-
-Per D14 (plan design decision), revert works by querying EXECUTED events
-for an approval, deriving candidate inverse commands using a hardcoded
-best-effort mapping, and presenting them for user confirmation.
-
-Public API:
-    InverseCommand     -- dataclass for a candidate inverse operation
-    derive_inverse(event) -> InverseCommand | None
-    derive_inverses_for_approval(approval_id, con) -> list[InverseCommand]
-
-The InverseCommand dataclass carries:
-    event_id: int          -- the original EXECUTED event id
-    original_command: str  -- the original command (from payload or metadata)
-    inverse_command: str | None  -- the derived inverse, or None if NOT REVERSIBLE
-    reversible: bool       -- False when no inverse can be derived
-    notes: str             -- human-readable explanation
-"""
-
-from __future__ import annotations
-
-import json
-import re
-import sqlite3
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-
-@dataclass
-class InverseCommand:
-    """Candidate inverse operation for an EXECUTED approval event."""
-
-    event_id: int
-    original_command: str
-    inverse_command: Optional[str]
-    reversible: bool
-    notes: str
-
-
-# ---------------------------------------------------------------------------
-# Hardcoded verb -> inverse mapping (D14)
-# ---------------------------------------------------------------------------
-
-# Pattern-based inverse rules. Each entry is (pattern_re, inverse_template_fn).
-# The pattern is matched against the original command. The template function
-# receives the re.Match object and returns the inverse command string.
-_INVERSE_RULES: list[tuple[re.Pattern, Any]] = []
-
-
-def _rule(pattern: str):
-    """Decorator to register an inverse rule."""
-    def decorator(fn):
-        _INVERSE_RULES.append((re.compile(pattern), fn))
-        return fn
-    return decorator
-
-
-@_rule(r"^gaia\s+brief\s+set-status\s+(\S+)\s+done\s*$")
-def _brief_done_to_pending(m):
-    brief_id = m.group(1)
-    return f"gaia brief set-status {brief_id} pending"
-
-
-@_rule(r"^gaia\s+brief\s+set-status\s+(\S+)\s+active\s*$")
-def _brief_active_to_draft(m):
-    brief_id = m.group(1)
-    return f"gaia brief set-status {brief_id} draft"
-
-
-@_rule(r"^gaia\s+brief\s+set-status\s+(\S+)\s+pending\s*$")
-def _brief_pending_to_draft(m):
-    brief_id = m.group(1)
-    return f"gaia brief set-status {brief_id} draft"
-
-
-@_rule(r"^git\s+branch\s+(\S+)\s*$")
-def _git_branch_create_to_delete(m):
-    branch = m.group(1)
-    if branch.startswith("-"):
-        # Already a delete flag -- not a create
-        return None
-    return f"git branch -D {branch}"
-
-
-@_rule(r"^git\s+branch\s+-[bB]\s+(\S+)\s*$")
-def _git_branch_b_to_delete(m):
-    branch = m.group(1)
-    return f"git branch -D {branch}"
-
-
-@_rule(r"^rm\s+(.+)\s*$")
-def _rm_not_reversible(_m):
-    # rm has no generic inverse; caller sees NOT REVERSIBLE
-    return None
-
-
-def _derive_from_command_string(command: str) -> InverseCommand | None:
-    """Apply hardcoded rules to a single command string.
-
-    Returns an InverseCommand on the first match, or None when no rule matches.
-    """
-    cmd = command.strip()
-    for pattern, fn in _INVERSE_RULES:
-        m = pattern.match(cmd)
-        if m:
-            inverse = fn(m)
-            if inverse is not None:
-                return InverseCommand(
-                    event_id=0,
-                    original_command=cmd,
-                    inverse_command=inverse,
-                    reversible=True,
-                    notes=f"Derived from pattern: {pattern.pattern}",
-                )
-            else:
-                return InverseCommand(
-                    event_id=0,
-                    original_command=cmd,
-                    inverse_command=None,
-                    reversible=False,
-                    notes="NOT REVERSIBLE -- matched pattern has no safe inverse",
-                )
-    return None
-
-
-def _is_file_create(payload: dict, original_cmd: str) -> bool:
-    """Heuristic: detect if the payload represents a file creation."""
-    commands = payload.get("commands") or []
-    scope = payload.get("scope") or ""
-    # A Write tool on a new path is stored with 'write' or 'create' in operation.
-    operation = (payload.get("operation") or "").lower()
-    if "write" in operation or "create" in operation:
-        return True
-    # If the scope looks like a file path and command is a write-like verb
-    if scope and ("write" in original_cmd.lower() or "create" in original_cmd.lower()):
-        return True
-    return False
-
-
-def derive_inverse(event: Dict[str, Any]) -> InverseCommand:
-    """Derive a candidate inverse command for a single EXECUTED event.
-
-    Best-effort approach per D14:
-    - Tries hardcoded verb patterns first.
-    - Detects file create -> suggests rm <path>.
-    - Falls through to "NOT REVERSIBLE" with original command for reference.
-
-    Args:
-        event: A dict from store.replay_for_approval() representing an
-            EXECUTED event row. Must have 'id', 'payload_json', and
-            optionally 'metadata_json'.
-
-    Returns:
-        InverseCommand with reversible=True if an inverse was derived, or
-        reversible=False with inverse_command=None and a "NOT REVERSIBLE"
-        note.
-    """
-    event_id = event.get("id", 0)
-    payload_json = event.get("payload_json") or ""
-    metadata_json = event.get("metadata_json") or ""
-
-    payload: dict = {}
-    if payload_json:
-        try:
-            payload = json.loads(payload_json)
-        except (json.JSONDecodeError, TypeError):
-            pass
-
-    metadata: dict = {}
-    if metadata_json:
-        try:
-            metadata = json.loads(metadata_json)
-        except (json.JSONDecodeError, TypeError):
-            pass
-
-    # Collect commands to try inverting.
-    commands = payload.get("commands") or []
-    exact_content = payload.get("exact_content") or ""
-
-    # Build list of individual command strings to invert.
-    cmd_strings: list[str] = []
-    if commands:
-        cmd_strings = [str(c).strip() for c in commands if c]
-    elif exact_content:
-        # Split newline-separated commands per D13.
-        cmd_strings = [l.strip() for l in exact_content.splitlines() if l.strip()]
-
-    if not cmd_strings:
-        # No commands found -- check operation field.
-        operation = payload.get("operation") or ""
-        if operation:
-            cmd_strings = [operation]
-
-    if not cmd_strings:
-        return InverseCommand(
-            event_id=event_id,
-            original_command="(no command recorded)",
-            inverse_command=None,
-            reversible=False,
-            notes="NOT REVERSIBLE -- no command data found in event payload",
-        )
-
-    # For multi-command events, try to invert each command.
-    # If ALL have inverses, return a compound inverse. If any fails, NOT REVERSIBLE.
-    inverses = []
-    original_summary = "; ".join(cmd_strings)
-
-    for cmd in cmd_strings:
-        result = _derive_from_command_string(cmd)
-        if result is None:
-            # No rule matched -- check for file create heuristic.
-            scope = payload.get("scope") or ""
-            if scope and _is_file_create(payload, cmd):
-                # Suggest rm <scope> as the inverse.
-                scope_path = scope.strip()
-                inverses.append(
-                    InverseCommand(
-                        event_id=event_id,
-                        original_command=cmd,
-                        inverse_command=f"rm {scope_path}",
-                        reversible=True,
-                        notes=f"File create detected -- inverse is rm {scope_path} (requires confirm)",
-                    )
-                )
-            else:
-                return InverseCommand(
-                    event_id=event_id,
-                    original_command=original_summary,
-                    inverse_command=None,
-                    reversible=False,
-                    notes=f"NOT REVERSIBLE -- no inverse rule matches: {cmd!r}",
-                )
-        else:
-            result.event_id = event_id
-            inverses.append(result)
-
-    if len(inverses) == 1:
-        return inverses[0]
-
-    # Multiple inverses -- combine into a compound inverse.
-    combined_inverse = " && ".join(ic.inverse_command for ic in inverses if ic.inverse_command)
-    combined_notes = "; ".join(ic.notes for ic in inverses)
-    return InverseCommand(
-        event_id=event_id,
-        original_command=original_summary,
-        inverse_command=combined_inverse if combined_inverse else None,
-        reversible=bool(combined_inverse),
-        notes=combined_notes,
-    )
-
-
-def derive_inverses_for_approval(
-    approval_id: str,
-    con: sqlite3.Connection,
-) -> List[InverseCommand]:
-    """Return a list of InverseCommand for all EXECUTED events of an approval.
-
-    Args:
-        approval_id: The P-{uuid4} approval identifier.
-        con: An open sqlite3.Connection.
-
-    Returns:
-        List of InverseCommand, one per EXECUTED event, in insertion order.
-        Empty list if no EXECUTED events exist.
-    """
-    cur = con.execute(
-        "SELECT id, payload_json, metadata_json FROM approval_events "
-        "WHERE approval_id = ? AND event_type = 'EXECUTED' "
-        "ORDER BY id ASC",
-        (approval_id,),
-    )
-    rows = cur.fetchall()
-    result = []
-    for row in rows:
-        event = {
-            "id": row[0],
-            "payload_json": row[1],
-            "metadata_json": row[2],
-        }
-        result.append(derive_inverse(event))
-    return result