@jaguilar87/gaia 5.0.0-rc.2

package/hooks/modules/security/approval_grants.py

@@ -0,0 +1,1638 @@
+"""
+Approval grant management for T3 command passthrough.
+
+Two-phase nonce-based approval flow:
+
+  Phase 1 -- BLOCKING:
+    bash_validator detects a T3 command, generates a cryptographic nonce,
+    writes a pending-{nonce}.json file, and returns a block response that
+    includes the nonce for the agent to present.
+
+  Phase 2 -- ACTIVATION:
+    The orchestrator resumes the agent with "APPROVE:{nonce}". The
+    pre_tool_use hook finds the pending file, validates it (session, TTL,
+    nonce match), converts it to an active grant, and deletes the pending
+    file. The agent retries the command; bash_validator finds the active
+    grant and allows it.
+
+Grants are:
+- Scoped to a session (CLAUDE_SESSION_ID)
+- Time-limited (default 10 minutes)
+- Cleaned up after use or expiry
+- Stored in .claude/cache/approvals/
+
+Security properties:
+- Grants are created ONLY by the hook (not by agents)
+- Nonce-activated grants are scoped to a semantic command signature
+- Grants expire automatically
+- The deny list (blocked_commands.py) is NEVER bypassed -- grants only
+  override the dangerous verb detector
+- Nonces are 128-bit random hex (cannot be guessed)
+- Pending files are session-scoped (cannot be activated from another session)
+- A nonce can only be activated ONCE (pending file deleted on activation)
+"""
+
+import json
+import logging
+import os
+import re
+import secrets
+import subprocess
+import time
+from dataclasses import dataclass, field, asdict
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..core.paths import find_claude_dir, get_plugin_data_dir
+from ..core.state import get_session_id
+from .approval_scopes import (
+    ApprovalSignature,
+    SCOPE_FILE_PATH,
+    SCOPE_SEMANTIC_SIGNATURE,
+    SCOPE_VERB_FAMILY,
+    SUPPORTED_SCOPE_TYPES,
+    build_approval_signature,
+    build_file_path_signature,
+    matches_approval_signature,
+    matches_file_path_approval,
+)
+
+logger = logging.getLogger(__name__)
+
+# Default grant TTL in minutes
+DEFAULT_GRANT_TTL_MINUTES = 5
+
+# Default pending TTL in minutes (24 hours)
+DEFAULT_PENDING_TTL_MINUTES = 1440
+
+# Cleanup throttle: only run cleanup if 60+ seconds since last run
+_last_cleanup_time: float = 0.0
+_CLEANUP_INTERVAL_SECONDS = 60
+
+class ActivationStatus(str, Enum):
+    """Activation result statuses for pending approval flow."""
+    ACTIVATED = "activated"
+    NOT_FOUND = "not_found"
+    NONCE_MISMATCH = "nonce_mismatch"
+    SESSION_MISMATCH = "session_mismatch"
+    EXPIRED = "expired"
+    INVALID_SIGNATURE = "invalid_signature"
+    INVALID_PENDING = "invalid_pending"
+    ERROR = "error"
+
+
+# Backward-compatible module-level aliases
+ACTIVATION_ACTIVATED = ActivationStatus.ACTIVATED
+ACTIVATION_NOT_FOUND = ActivationStatus.NOT_FOUND
+ACTIVATION_NONCE_MISMATCH = ActivationStatus.NONCE_MISMATCH
+ACTIVATION_SESSION_MISMATCH = ActivationStatus.SESSION_MISMATCH
+ACTIVATION_EXPIRED = ActivationStatus.EXPIRED
+ACTIVATION_INVALID_SIGNATURE = ActivationStatus.INVALID_SIGNATURE
+ACTIVATION_INVALID_PENDING = ActivationStatus.INVALID_PENDING
+ACTIVATION_ERROR = ActivationStatus.ERROR
+
+
+def _is_ttl_expired(timestamp: float, ttl_minutes: int) -> bool:
+    """Return True if the given timestamp is older than ttl_minutes.
+
+    A ttl_minutes of 0 means "no expiry" -- always returns False.
+    """
+    if ttl_minutes == 0:
+        return False
+    if timestamp == 0:
+        return True
+    elapsed_minutes = (time.time() - timestamp) / 60
+    return elapsed_minutes > ttl_minutes
+
+
+def _is_rejected(data: Dict[str, Any]) -> bool:
+    """Return True if a pending approval has been rejected."""
+    return data.get("status") == "rejected"
+
+
+@dataclass(frozen=True)
+class ApprovalActivationResult:
+    """Structured result for pending approval activation."""
+
+    success: bool
+    status: str
+    reason: str
+    grant_path: Optional[Path] = None
+
+
+@dataclass
+class ApprovalGrant:
+    """A time-limited approval grant for T3 commands.
+
+    Attributes:
+        session_id: The Claude session that owns this grant.
+        approved_verbs: Human-readable verb summary for logs/debugging.
+        approved_scope: Original approval scope text from the user.
+        scope_type: Approval scope mode (exact, semantic, or verb_family).
+        scope_signature: Persisted ApprovalSignature payload for matching.
+        granted_at: Unix timestamp when the grant was created.
+        ttl_minutes: How long the grant is valid.
+        used: Whether the grant has been consumed.
+        multi_use: When True, the grant is NOT consumed after a single use.
+            Used by SCOPE_VERB_FAMILY grants for batch operations.
+    """
+    session_id: str = ""
+    approved_verbs: List[str] = field(default_factory=list)
+    approved_scope: str = ""
+    scope_type: str = SCOPE_SEMANTIC_SIGNATURE
+    scope_signature: Optional[dict] = None
+    granted_at: float = 0.0
+    ttl_minutes: int = DEFAULT_GRANT_TTL_MINUTES
+    used: bool = False
+    confirmed: bool = False
+    multi_use: bool = False
+
+    def is_expired(self) -> bool:
+        """Check if the grant has expired."""
+        return _is_ttl_expired(self.granted_at, self.ttl_minutes)
+
+    def is_valid(self) -> bool:
+        """Check if the grant is still usable.
+
+        Multi-use grants ignore the ``used`` flag and remain valid until
+        their TTL expires.
+        """
+        if self.is_expired():
+            return False
+        if self.multi_use:
+            return True
+        return not self.used
+
+    def get_signature(self) -> Optional[ApprovalSignature]:
+        """Deserialize the persisted scope signature, if present."""
+        if not self.scope_signature:
+            return None
+        try:
+            return ApprovalSignature.from_dict(self.scope_signature)
+        except Exception:
+            return None
+
+    def matches_command(self, command: str) -> bool:
+        """Check whether a command falls inside this grant's explicit scope."""
+        signature = self.get_signature()
+        if signature is None:
+            return False
+        return matches_approval_signature(signature, command)
+
+
+_grants_dir_created: bool = False
+
+# Module-level flag: set by check_approval_grant() when it encounters and
+# cleans up an expired grant for the requested command.  Callers (e.g.
+# bash_validator) can read this via last_check_found_expired() to emit a
+# clear expiry message instead of a generic "no grant found" block.
+_last_check_found_expired: bool = False
+
+
+def last_check_found_expired() -> bool:
+    """Return True if the most recent check_approval_grant() call cleaned up
+    an expired grant that would have matched the command."""
+    return _last_check_found_expired
+
+
+def _get_grants_dir() -> Path:
+    """Get the directory for approval grant files."""
+    global _grants_dir_created
+    grants_dir = get_plugin_data_dir() / "cache" / "approvals"
+    if not _grants_dir_created:
+        grants_dir.mkdir(parents=True, exist_ok=True)
+        _grants_dir_created = True
+    return grants_dir
+
+
+def _get_pending_index_path(session_id: str) -> Path:
+    """Return the session-scoped pending-approval index path."""
+    return _get_grants_dir() / f"pending-index-{session_id}.json"
+
+
+def _read_json_file(path: Path) -> Optional[Dict[str, Any]]:
+    """Read a JSON file defensively and return its dict payload."""
+    try:
+        return json.loads(path.read_text())
+    except Exception:
+        return None
+
+
+def _rebuild_pending_index(session_id: str) -> None:
+    """Rebuild the per-session pending-approval index from authoritative files."""
+    index_path = _get_pending_index_path(session_id)
+    entries: List[Dict[str, Any]] = []
+
+    for pending_file in _get_grants_dir().glob("pending-*.json"):
+        if pending_file.name.startswith("pending-index-"):
+            continue
+        data = _read_json_file(pending_file)
+        if not data or data.get("session_id") != session_id:
+            continue
+        if _is_rejected(data):
+            continue
+
+        nonce = data.get("nonce")
+        timestamp = data.get("timestamp")
+        if not nonce or not isinstance(timestamp, (int, float)):
+            continue
+        ttl_minutes = data.get("ttl_minutes", DEFAULT_PENDING_TTL_MINUTES)
+        if _is_ttl_expired(float(timestamp), int(ttl_minutes)):
+            continue
+
+        entries.append(
+            {
+                "nonce": nonce,
+                "pending_file": pending_file.name,
+                "timestamp": float(timestamp),
+            }
+        )
+
+    entries.sort(key=lambda item: item["timestamp"], reverse=True)
+
+    if not entries:
+        index_path.unlink(missing_ok=True)
+        return
+
+    index_payload = {
+        "session_id": session_id,
+        "latest_nonce": entries[0]["nonce"],
+        "entries": entries,
+    }
+    index_path.write_text(json.dumps(index_payload, indent=2))
+
+
+def _get_session_id() -> str:
+    """Get the current session ID. Delegates to core.state.get_session_id()."""
+    return get_session_id()
+
+
+def get_latest_pending_approval(session_id: Optional[str] = None) -> Optional[Dict[str, Any]]:
+    """Return the newest pending approval record for the current session.
+
+    This is a deterministic helper for future orchestrator logic: it reads the
+    session index, then dereferences the authoritative pending file instead of
+    asking callers to parse a nonce from agent text.
+    """
+    if session_id is None:
+        session_id = _get_session_id()
+
+    index_path = _get_pending_index_path(session_id)
+
+    for attempt in range(2):
+        if not index_path.exists():
+            return None
+
+        index_data = _read_json_file(index_path)
+        if not index_data:
+            _rebuild_pending_index(session_id)
+            continue
+
+        latest_nonce = index_data.get("latest_nonce")
+        entries = index_data.get("entries") or []
+        pending_ref = next((entry for entry in entries if entry.get("nonce") == latest_nonce), None)
+        if not latest_nonce or pending_ref is None:
+            _rebuild_pending_index(session_id)
+            continue
+
+        pending_path = _get_grants_dir() / pending_ref.get("pending_file", "")
+        pending_data = _read_json_file(pending_path)
+        if not pending_data or pending_data.get("session_id") != session_id:
+            _rebuild_pending_index(session_id)
+            continue
+
+        return pending_data
+
+    return None
+
+
+# ============================================================================
+# Nonce Generation and Pending Approval Management
+# ============================================================================
+
+def generate_nonce() -> str:
+    """Generate a cryptographic nonce for approval tracking.
+
+    Returns:
+        32-character hex string (128 bits of entropy).
+    """
+    return secrets.token_hex(16)
+
+
+# Regex for extracting a nonce from an AskUserQuestion approve label.
+# Only matches labels that start with "Approve" and contain [P-<hex>].
+_APPROVE_NONCE_RE = re.compile(r"^Approve\b.*\[P-([a-f0-9]+)\]")
+
+
+def extract_nonce_from_label(label: str) -> Optional[str]:
+    """Extract the nonce from an AskUserQuestion option label.
+
+    Approve labels may contain a ``[P-<hex>]`` tag that identifies the
+    pending approval to activate.  Reject labels never carry a nonce,
+    even if one is superficially present in the text.
+
+    Args:
+        label: The option label string (e.g. ``"Approve -- git push origin main [P-e68be5b8]"``).
+
+    Returns:
+        The hex nonce string if found in an Approve label, otherwise ``None``.
+    """
+    m = _APPROVE_NONCE_RE.search(label)
+    return m.group(1) if m else None
+
+
+def load_pending_by_nonce_prefix(prefix: str) -> Optional[Dict[str, Any]]:
+    """Load a pending approval file whose nonce starts with the given prefix.
+
+    The ``[P-<hex>]`` tag in AskUserQuestion labels carries the first 8
+    characters of the full 32-character nonce.  This function scans the
+    grants directory for a matching ``pending-{nonce}.json`` file and
+    returns its parsed contents.
+
+    If multiple files match (extremely unlikely with 8 hex chars), the
+    most recent one (by timestamp) is returned.
+
+    Args:
+        prefix: Hex prefix extracted from a ``[P-xxx]`` label (typically 8 chars).
+
+    Returns:
+        The parsed pending approval dict, or ``None`` if no match was found.
+    """
+    try:
+        grants_dir = _get_grants_dir()
+        candidates: List[Dict[str, Any]] = []
+
+        for pending_file in grants_dir.glob("pending-*.json"):
+            if pending_file.name.startswith("pending-index-"):
+                continue
+            # Extract nonce from filename: pending-{nonce}.json
+            fname_nonce = pending_file.stem.removeprefix("pending-")
+            if not fname_nonce.startswith(prefix):
+                continue
+            data = _read_json_file(pending_file)
+            if data and not _is_rejected(data):
+                candidates.append(data)
+
+        if not candidates:
+            logger.info("No pending approval found for nonce prefix %s", prefix)
+            return None
+
+        # Return newest by timestamp
+        candidates.sort(key=lambda d: d.get("timestamp", 0), reverse=True)
+        logger.info(
+            "Found pending approval for nonce prefix %s: full_nonce=%s",
+            prefix, candidates[0].get("nonce", "?")[:12],
+        )
+        return candidates[0]
+
+    except Exception as e:
+        logger.error("Error loading pending by nonce prefix %s: %s", prefix, e)
+        return None
+
+
+# ------------------------------------------------------------------ #
+# Environment snapshot capture
+# ------------------------------------------------------------------ #
+
+# CLI families whose environment state is worth capturing at blocking time.
+_GIT_CMD_PATTERN = re.compile(r"\bgit\b")
+
+_ENV_SNAPSHOT_TIMEOUT_SECONDS = 2
+
+
+def _run_git_query(args: List[str], cwd: Optional[str] = None) -> Optional[str]:
+    """Run a git sub-command and return stripped stdout, or None on failure."""
+    try:
+        result = subprocess.run(
+            ["git"] + args,
+            capture_output=True,
+            text=True,
+            timeout=_ENV_SNAPSHOT_TIMEOUT_SECONDS,
+            cwd=cwd,
+        )
+        if result.returncode == 0:
+            return result.stdout.strip()
+    except Exception:
+        pass
+    return None
+
+
+def capture_environment_snapshot(
+    command: str,
+    cwd: Optional[str] = None,
+) -> Dict[str, Any]:
+    """Capture relevant environment state at the time a command is blocked.
+
+    Designed to be fast (<2 s) and failure-tolerant -- a failed capture
+    returns an empty dict and MUST NOT prevent the pending file from being
+    written.
+
+    Currently supports:
+    - **git** commands: local HEAD, remote HEAD (origin/main), current branch.
+
+    Extensible to kubectl, terraform, etc. in future iterations.
+
+    Args:
+        command: The blocked command string.
+        cwd: Working directory context (used for git queries).
+
+    Returns:
+        A dict with captured state, or ``{}`` if nothing could be captured
+        or the command class is not yet supported.
+    """
+    if not _GIT_CMD_PATTERN.search(command):
+        return {}
+
+    try:
+        snapshot: Dict[str, Any] = {"command_class": "git"}
+
+        head = _run_git_query(["rev-parse", "HEAD"], cwd=cwd)
+        if head:
+            snapshot["local_head"] = head
+
+        branch = _run_git_query(["rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd)
+        if branch:
+            snapshot["branch"] = branch
+
+        remote_head = _run_git_query(
+            ["rev-parse", "origin/main"], cwd=cwd,
+        )
+        if remote_head:
+            snapshot["remote_head"] = remote_head
+
+        return snapshot
+
+    except Exception as exc:
+        logger.debug("Environment snapshot capture failed: %s", exc)
+        return {}
+
+
+def write_pending_approval(
+    nonce: str,
+    command: str,
+    danger_verb: str,
+    danger_category: str,
+    session_id: Optional[str] = None,
+    ttl_minutes: int = DEFAULT_PENDING_TTL_MINUTES,
+    context: Optional[Dict[str, Any]] = None,
+    cwd: Optional[str] = None,
+    environment: Optional[Dict[str, Any]] = None,
+) -> Optional[Path]:
+    """Write a pending approval file when a T3 command is blocked.
+
+    Called by bash_validator when it detects a dangerous command and blocks it.
+    The nonce is included in the block response so the agent can present it
+    to the user for approval.
+
+    Args:
+        nonce: Cryptographic nonce from generate_nonce().
+        command: The command that was blocked.
+        danger_verb: The dangerous verb detected (e.g., "push", "apply").
+        danger_category: The danger category (e.g., "MUTATIVE", "DESTRUCTIVE").
+        session_id: Session ID (defaults to CLAUDE_SESSION_ID env var).
+        ttl_minutes: How long the pending approval is valid before expiry
+            (0 = no expiry).
+        context: Optional dict with enriched context (source, description,
+            risk, rollback, branch, files_changed, etc.).
+        cwd: Optional working directory where the command was invoked.
+        environment: Optional dict with environment state at blocking time.
+            If not provided, auto-captured via capture_environment_snapshot().
+
+    Returns:
+        Path to the pending file, or None on failure.
+    """
+    if session_id is None:
+        session_id = _get_session_id()
+
+    signature = build_approval_signature(
+        command,
+        scope_type=SCOPE_SEMANTIC_SIGNATURE,
+        danger_verb=danger_verb,
+        danger_category=danger_category,
+    )
+    if signature is None:
+        logger.error(
+            "Failed to build semantic approval signature for pending command: %s",
+            command,
+        )
+        return None
+
+    # Auto-capture environment if not explicitly provided.
+    if environment is None:
+        try:
+            environment = capture_environment_snapshot(command, cwd=cwd)
+        except Exception as exc:
+            logger.debug("Auto environment capture failed (non-fatal): %s", exc)
+            environment = {}
+
+    pending_data = {
+        "nonce": nonce,
+        "session_id": session_id,
+        "command": command,
+        "danger_verb": danger_verb,
+        "danger_category": danger_category,
+        "scope_type": signature.scope_type,
+        "scope_signature": signature.to_dict(),
+        "timestamp": time.time(),
+        "ttl_minutes": ttl_minutes,
+        "context": context or {},
+        "environment": environment,
+    }
+    if cwd is not None:
+        pending_data["cwd"] = cwd
+
+    try:
+        grants_dir = _get_grants_dir()
+        pending_file = grants_dir / f"pending-{nonce}.json"
+        pending_file.write_text(json.dumps(pending_data, indent=2))
+        _rebuild_pending_index(session_id)
+
+        logger.info(
+            "Pending approval written: nonce=%s, verb=%s, category=%s, session=%s",
+            nonce, danger_verb, danger_category, session_id,
+        )
+        return pending_file
+
+    except Exception as e:
+        logger.error("Failed to write pending approval: %s", e)
+        return None
+
+
+def activate_pending_approval(
+    nonce: str,
+    session_id: Optional[str] = None,
+    ttl_minutes: int = DEFAULT_GRANT_TTL_MINUTES,
+) -> ApprovalActivationResult:
+    """Activate a pending approval by converting it to an active grant.
+
+    Called by the pre_tool_use hook when it detects "APPROVE:{nonce}" in a
+    Task resume prompt. Validates the pending file, creates an active grant,
+    and deletes the pending file.
+
+    Args:
+        nonce: The nonce from the APPROVE: token.
+        session_id: Current session ID for validation.
+        ttl_minutes: TTL for the active grant.
+
+    Returns:
+        Structured activation result with status and optional grant path.
+    """
+    if session_id is None:
+        session_id = _get_session_id()
+
+    try:
+        grants_dir = _get_grants_dir()
+        pending_file = grants_dir / f"pending-{nonce}.json"
+
+        # Pending file must exist
+        if not pending_file.exists():
+            logger.warning(
+                "Pending approval not found for nonce %s -- "
+                "may have expired or already been activated",
+                nonce,
+            )
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_NOT_FOUND,
+                reason="Pending approval not found. It may have expired or already been used.",
+            )
+
+        # Read and validate pending data
+        pending_data = json.loads(pending_file.read_text())
+
+        # Validate nonce matches exactly
+        if pending_data.get("nonce") != nonce:
+            logger.warning("Nonce mismatch in pending file: expected %s", nonce)
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_NONCE_MISMATCH,
+                reason="Nonce mismatch while activating approval.",
+            )
+
+        # Validate session matches
+        if pending_data.get("session_id") != session_id:
+            logger.warning(
+                "Session mismatch for nonce %s: pending=%s, current=%s",
+                nonce, pending_data.get("session_id"), session_id,
+            )
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_SESSION_MISMATCH,
+                reason="Approval was issued for a different Claude session.",
+            )
+
+        # Validate not expired
+        pending_timestamp = pending_data.get("timestamp", 0)
+        pending_ttl = pending_data.get("ttl_minutes", DEFAULT_PENDING_TTL_MINUTES)
+        if _is_ttl_expired(pending_timestamp, pending_ttl):
+            logger.warning(
+                "Pending approval expired for nonce %s: TTL=%d min",
+                nonce, pending_ttl,
+            )
+            # Clean up expired pending file
+            _cleanup_grant(pending_file)
+            _rebuild_pending_index(session_id)
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_EXPIRED,
+                reason="Approval nonce expired before activation.",
+            )
+
+        command = pending_data.get("command", "")
+        danger_verb = pending_data.get("danger_verb", "")
+        scope_signature_data = pending_data.get("scope_signature")
+        if not scope_signature_data:
+            logger.warning("Pending approval for nonce %s is missing scope_signature", nonce)
+            _cleanup_grant(pending_file)
+            _rebuild_pending_index(session_id)
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_INVALID_PENDING,
+                reason="Pending approval file is missing a semantic signature.",
+            )
+
+        signature = ApprovalSignature.from_dict(scope_signature_data)
+        if signature.scope_type not in (SCOPE_SEMANTIC_SIGNATURE, SCOPE_FILE_PATH):
+            logger.warning(
+                "Pending approval for nonce %s has unsupported scope_type=%s",
+                nonce,
+                signature.scope_type,
+            )
+            _cleanup_grant(pending_file)
+            _rebuild_pending_index(session_id)
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_INVALID_SIGNATURE,
+                reason="Pending approval uses an unsupported scope type.",
+            )
+
+        # For file-path scopes, verb validation is not applicable.
+        if signature.scope_type == SCOPE_FILE_PATH:
+            verbs = ["write"]
+        elif not signature.verb and not danger_verb:
+            logger.warning(
+                "Could not validate semantic signature for pending approval command: %s",
+                command,
+            )
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_INVALID_SIGNATURE,
+                reason="Approval signature could not be validated safely.",
+            )
+        else:
+            verbs = [signature.verb] if signature.verb else ([danger_verb.lower()] if danger_verb else [])
+
+        # Create active grant
+        grant = ApprovalGrant(
+            session_id=session_id,
+            approved_verbs=verbs,
+            approved_scope=command,
+            scope_type=signature.scope_type,
+            scope_signature=signature.to_dict(),
+            granted_at=time.time(),
+            ttl_minutes=ttl_minutes,
+        )
+
+        grant_file = grants_dir / f"grant-{session_id}-{int(time.time() * 1000)}-{nonce[:8]}.json"
+        grant_file.write_text(json.dumps(asdict(grant), indent=2))
+
+        # Delete pending file (one-time activation)
+        _cleanup_grant(pending_file)
+        _rebuild_pending_index(session_id)
+
+        logger.info(
+            "Pending approval activated: nonce=%s, verbs=%s, grant=%s",
+            nonce, verbs, grant_file.name,
+        )
+        return ApprovalActivationResult(
+            success=True,
+            status=ACTIVATION_ACTIVATED,
+            reason="Pending approval activated.",
+            grant_path=grant_file,
+        )
+
+    except (json.JSONDecodeError, TypeError) as e:
+        logger.error("Invalid pending approval file for nonce %s: %s", nonce, e)
+        return ApprovalActivationResult(
+            success=False,
+            status=ACTIVATION_INVALID_PENDING,
+            reason="Pending approval file is invalid or corrupt.",
+        )
+    except Exception as e:
+        logger.error("Failed to activate pending approval: %s", e)
+        return ApprovalActivationResult(
+            success=False,
+            status=ACTIVATION_ERROR,
+            reason="Unexpected error while activating approval.",
+        )
+
+def activate_cross_session_pending(
+    pending_data: dict,
+    ttl_minutes: int = DEFAULT_GRANT_TTL_MINUTES,
+    session_id: Optional[str] = None,
+) -> ApprovalActivationResult:
+    """Create an active grant from a pending file that belongs to a prior session.
+
+    Called ONLY when the user has already confirmed approval via AskUserQuestion.
+    Unlike activate_pending_approval(), this function skips the session_id equality
+    check because the pending file is from a previous session whose nonce can never
+    match the current session.  All other validation (nonce presence, TTL, signature)
+    is performed normally.
+
+    The new grant is created under the CURRENT session ID so that
+    check_approval_grant() can find it when the dispatched agent runs the command.
+    confirmed is set to True directly because the human has already approved.
+
+    Args:
+        pending_data: The dict loaded from a pending-{nonce}.json file.
+        ttl_minutes: TTL for the active grant (default DEFAULT_GRANT_TTL_MINUTES).
+        session_id: Optional explicit session ID to use for the new grant.  When
+            provided this value is used directly, which avoids relying on the
+            CLAUDE_SESSION_ID environment variable -- important when the function
+            is called from a dispatched agent's subprocess where the env var may
+            not be set.  Defaults to None, which falls back to _get_session_id()
+            (backward compatible).
+
+    Returns:
+        Structured activation result with status and optional grant path.
+    """
+    current_session_id = session_id if session_id is not None else _get_session_id()
+
+    try:
+        grants_dir = _get_grants_dir()
+
+        # Validate required fields
+        nonce = pending_data.get("nonce")
+        if not nonce:
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_INVALID_PENDING,
+                reason="Pending approval file is missing a nonce.",
+            )
+
+        pending_file = grants_dir / f"pending-{nonce}.json"
+
+        # Validate not expired (TTL check still applies)
+        pending_timestamp = pending_data.get("timestamp", 0)
+        pending_ttl = pending_data.get("ttl_minutes", DEFAULT_PENDING_TTL_MINUTES)
+        if _is_ttl_expired(pending_timestamp, pending_ttl):
+            logger.warning(
+                "Cross-session pending approval expired for nonce %s: TTL=%d min",
+                nonce, pending_ttl,
+            )
+            _cleanup_grant(pending_file)
+            prior_session_id = pending_data.get("session_id", "unknown")
+            _rebuild_pending_index(prior_session_id)
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_EXPIRED,
+                reason="Approval nonce expired before cross-session activation.",
+            )
+
+        command = pending_data.get("command", "")
+        danger_verb = pending_data.get("danger_verb", "")
+        scope_signature_data = pending_data.get("scope_signature")
+        if not scope_signature_data:
+            logger.warning(
+                "Cross-session pending approval for nonce %s is missing scope_signature",
+                nonce,
+            )
+            _cleanup_grant(pending_file)
+            prior_session_id = pending_data.get("session_id", "unknown")
+            _rebuild_pending_index(prior_session_id)
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_INVALID_PENDING,
+                reason="Pending approval file is missing a semantic signature.",
+            )
+
+        signature = ApprovalSignature.from_dict(scope_signature_data)
+        if signature.scope_type not in (SCOPE_SEMANTIC_SIGNATURE, SCOPE_FILE_PATH):
+            logger.warning(
+                "Cross-session pending for nonce %s has unsupported scope_type=%s",
+                nonce,
+                signature.scope_type,
+            )
+            _cleanup_grant(pending_file)
+            prior_session_id = pending_data.get("session_id", "unknown")
+            _rebuild_pending_index(prior_session_id)
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_INVALID_SIGNATURE,
+                reason="Pending approval uses an unsupported scope type.",
+            )
+
+        # For file-path scopes, verb validation is not applicable.
+        if signature.scope_type == SCOPE_FILE_PATH:
+            verbs = ["write"]
+        elif not signature.verb and not danger_verb:
+            logger.warning(
+                "Could not validate semantic signature for cross-session command: %s",
+                command,
+            )
+            return ApprovalActivationResult(
+                success=False,
+                status=ACTIVATION_INVALID_SIGNATURE,
+                reason="Approval signature could not be validated safely.",
+            )
+        else:
+            verbs = [signature.verb] if signature.verb else ([danger_verb.lower()] if danger_verb else [])
+
+        # Create active grant under the CURRENT session; confirmed=True because
+        # the human already approved via AskUserQuestion.
+        grant = ApprovalGrant(
+            session_id=current_session_id,
+            approved_verbs=verbs,
+            approved_scope=command,
+            scope_type=signature.scope_type,
+            scope_signature=signature.to_dict(),
+            granted_at=time.time(),
+            ttl_minutes=ttl_minutes,
+            confirmed=True,
+        )
+
+        grant_file = grants_dir / f"grant-{current_session_id}-{int(time.time() * 1000)}-{nonce[:8]}.json"
+        grant_file.write_text(json.dumps(asdict(grant), indent=2))
+
+        # Delete the old pending file (one-time activation)
+        _cleanup_grant(pending_file)
+        prior_session_id = pending_data.get("session_id", "unknown")
+        _rebuild_pending_index(prior_session_id)
+
+        logger.info(
+            "Cross-session pending activated: nonce=%s, prior_session=%s, "
+            "current_session=%s, verbs=%s, grant=%s",
+            nonce, prior_session_id, current_session_id, verbs, grant_file.name,
+        )
+        return ApprovalActivationResult(
+            success=True,
+            status=ACTIVATION_ACTIVATED,
+            reason="Cross-session pending approval activated.",
+            grant_path=grant_file,
+        )
+
+    except (json.JSONDecodeError, TypeError) as e:
+        logger.error("Invalid pending approval data for cross-session activation: %s", e)
+        return ApprovalActivationResult(
+            success=False,
+            status=ACTIVATION_INVALID_PENDING,
+            reason="Pending approval data is invalid or corrupt.",
+        )
+    except Exception as e:
+        logger.error("Failed to activate cross-session pending approval: %s", e)
+        return ApprovalActivationResult(
+            success=False,
+            status=ACTIVATION_ERROR,
+            reason="Unexpected error while activating cross-session approval.",
+        )
+
+
+def check_approval_grant(command: str, session_id: str = None) -> Optional[ApprovalGrant]:
+    """Check if there is an active approval grant for a command.
+
+    Called by the bash_validator before blocking a dangerous command.
+    If a valid grant exists that matches the command, the command should
+    be allowed through.
+
+    Args:
+        command: The shell command to check.
+        session_id: Session ID for grant scoping (defaults to env var).
+
+    Returns:
+        The matching ApprovalGrant if found and valid, None otherwise.
+    """
+    global _last_check_found_expired
+    _last_check_found_expired = False
+
+    if not session_id:
+        session_id = _get_session_id()
+
+    try:
+        grants_dir = _get_grants_dir()
+        if not grants_dir.exists():
+            return None
+
+        # Scan grant files for this session
+        for grant_file in sorted(grants_dir.glob(f"grant-{session_id}-*.json")):
+            try:
+                data = json.loads(grant_file.read_text())
+                grant = ApprovalGrant(**data)
+
+                # Skip expired or used grants
+                if not grant.is_valid():
+                    # Clean up expired grants; track if it would have matched
+                    if grant.is_expired():
+                        if grant.matches_command(command):
+                            _last_check_found_expired = True
+                        _cleanup_grant(grant_file)
+                    continue
+
+                signature = grant.get_signature()
+                if signature is None or signature.scope_type not in SUPPORTED_SCOPE_TYPES:
+                    logger.warning("Removing unsupported approval grant file %s", grant_file)
+                    _cleanup_grant(grant_file)
+                    continue
+
+                # Check if command matches the explicit scope signature
+                if grant.matches_command(command):
+                    logger.info(
+                        "Approval grant matched: command='%s', scope='%s', type=%s",
+                        command[:80], grant.approved_scope, grant.scope_type,
+                    )
+                    return grant
+
+            except (json.JSONDecodeError, TypeError) as e:
+                logger.warning("Invalid grant file %s: %s", grant_file, e)
+                _cleanup_grant(grant_file)
+                continue
+
+    except Exception as e:
+        logger.error("Error checking approval grants: %s", e)
+
+    return None
+
+
+def consume_grant(command: str, session_id: str = None) -> bool:
+    """Mark the first matching valid grant as used and persist to disk.
+
+    Called by bash_validator immediately after check_approval_grant() returns
+    a match, so that the grant can only be used once (single-use).
+
+    Args:
+        command: The shell command whose grant should be consumed.
+        session_id: Session ID for grant scoping (defaults to env var).
+
+    Returns:
+        True if a grant was found and consumed, False otherwise.
+    """
+    if not session_id:
+        session_id = _get_session_id()
+
+    try:
+        grants_dir = _get_grants_dir()
+        if not grants_dir.exists():
+            return False
+
+        for grant_file in sorted(grants_dir.glob(f"grant-{session_id}-*.json")):
+            try:
+                data = json.loads(grant_file.read_text())
+                grant = ApprovalGrant(**data)
+
+                if not grant.is_valid():
+                    if grant.is_expired():
+                        _cleanup_grant(grant_file)
+                    continue
+
+                signature = grant.get_signature()
+                if signature is None or signature.scope_type not in SUPPORTED_SCOPE_TYPES:
+                    continue
+
+                if grant.matches_command(command):
+                    if grant.multi_use:
+                        logger.info(
+                            "Grant matched (multi-use, not consumed): command='%s', grant=%s",
+                            command[:80], grant_file.name,
+                        )
+                        return True
+                    data["used"] = True
+                    grant_file.write_text(json.dumps(data, indent=2))
+                    logger.info(
+                        "Grant consumed (single-use): command='%s', grant=%s",
+                        command[:80], grant_file.name,
+                    )
+                    return True
+
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+    except Exception as e:
+        logger.error("Error consuming grant: %s", e)
+
+    return False
+
+
+def consume_session_grants(session_id: str = None) -> int:
+    """Consume all confirmed grants for a session.
+
+    Called at SubagentStop to clean up all grants that were used during the
+    subagent's lifetime. Multi-use grants are also consumed (session is over).
+
+    Args:
+        session_id: Session ID to scope consumption (defaults to env var).
+
+    Returns:
+        Number of grants consumed.
+    """
+    if not session_id:
+        session_id = _get_session_id()
+
+    consumed_count = 0
+    try:
+        grants_dir = _get_grants_dir()
+        if not grants_dir.exists():
+            return 0
+
+        for grant_file in sorted(grants_dir.glob(f"grant-{session_id}-*.json")):
+            try:
+                data = json.loads(grant_file.read_text())
+                grant = ApprovalGrant(**data)
+
+                if grant.used:
+                    continue  # already consumed
+
+                if not grant.is_valid():
+                    if grant.is_expired():
+                        _cleanup_grant(grant_file)
+                    continue
+
+                # Consume all confirmed grants (single-use and multi-use)
+                if grant.confirmed:
+                    data["used"] = True
+                    grant_file.write_text(json.dumps(data, indent=2))
+                    consumed_count += 1
+                    logger.info(
+                        "Grant consumed at SubagentStop: grant=%s, multi_use=%s",
+                        grant_file.name, grant.multi_use,
+                    )
+
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+    except Exception as e:
+        logger.error("Error consuming session grants: %s", e)
+
+    return consumed_count
+
+
+def confirm_grant(command: str, session_id: str = None) -> bool:
+    """Mark the first unconfirmed grant matching command as confirmed.
+
+    Called after the native permission dialog accepts the first T3 execution.
+    Subsequent T3 commands within the TTL window will see ``confirmed=True``
+    and be auto-allowed without a native dialog.
+
+    Args:
+        command: The shell command whose grant should be confirmed.
+        session_id: Session ID for grant scoping (defaults to env var).
+
+    Returns:
+        True if a grant was found and confirmed, False otherwise.
+    """
+    if not session_id:
+        session_id = _get_session_id()
+
+    try:
+        grants_dir = _get_grants_dir()
+        if not grants_dir.exists():
+            return False
+
+        for grant_file in sorted(grants_dir.glob(f"grant-{session_id}-*.json")):
+            try:
+                data = json.loads(grant_file.read_text())
+                grant = ApprovalGrant(**data)
+
+                if not grant.is_valid():
+                    if grant.is_expired():
+                        _cleanup_grant(grant_file)
+                    continue
+
+                if grant.confirmed:
+                    continue
+
+                signature = grant.get_signature()
+                if signature is None or signature.scope_type not in SUPPORTED_SCOPE_TYPES:
+                    continue
+
+                if grant.matches_command(command):
+                    data["confirmed"] = True
+                    grant_file.write_text(json.dumps(data, indent=2))
+                    logger.info(
+                        "Grant confirmed: command='%s', grant=%s",
+                        command[:80], grant_file.name,
+                    )
+                    return True
+
+            except (json.JSONDecodeError, TypeError):
+                continue
+
+    except Exception as e:
+        logger.error("Error confirming grant: %s", e)
+
+    return False
+
+
+def cleanup_expired_grants() -> int:
+    """Remove expired grant and pending files.
+
+    Called periodically (e.g., at hook startup) to prevent accumulation.
+    Throttled to run at most once every _CLEANUP_INTERVAL_SECONDS.
+
+    Returns:
+        Number of files cleaned up.
+    """
+    global _last_cleanup_time
+    now = time.time()
+    if now - _last_cleanup_time < _CLEANUP_INTERVAL_SECONDS:
+        return 0
+    _last_cleanup_time = now
+
+    cleaned = 0
+    sessions_to_rebuild: set[str] = set()
+    try:
+        grants_dir = _get_grants_dir()
+        if not grants_dir.exists():
+            return 0
+
+        # Clean up expired active grants
+        for grant_file in grants_dir.glob("grant-*.json"):
+            try:
+                data = json.loads(grant_file.read_text())
+                grant = ApprovalGrant(**data)
+                signature = grant.get_signature()
+                if signature is None or signature.scope_type not in SUPPORTED_SCOPE_TYPES:
+                    _cleanup_grant(grant_file)
+                    cleaned += 1
+                    continue
+                if grant.is_expired():
+                    _cleanup_grant(grant_file)
+                    cleaned += 1
+            except Exception:
+                # Corrupt file, remove it
+                _cleanup_grant(grant_file)
+                cleaned += 1
+
+        # Clean up expired pending approvals
+        for pending_file in grants_dir.glob("pending-*.json"):
+            if pending_file.name.startswith("pending-index-"):
+                continue
+            try:
+                data = json.loads(pending_file.read_text())
+                session_id = data.get("session_id")
+                if not data.get("scope_signature"):
+                    _cleanup_grant(pending_file)
+                    if session_id:
+                        sessions_to_rebuild.add(session_id)
+                    cleaned += 1
+                    continue
+                if _is_rejected(data):
+                    _cleanup_grant(pending_file)
+                    if session_id:
+                        sessions_to_rebuild.add(session_id)
+                    cleaned += 1
+                    continue
+                timestamp = data.get("timestamp", 0)
+                ttl = data.get("ttl_minutes", DEFAULT_PENDING_TTL_MINUTES)
+                if _is_ttl_expired(timestamp, ttl):
+                    _cleanup_grant(pending_file)
+                    if session_id:
+                        sessions_to_rebuild.add(session_id)
+                    cleaned += 1
+            except Exception:
+                # Corrupt file, remove it
+                data = _read_json_file(pending_file)
+                if data and data.get("session_id"):
+                    sessions_to_rebuild.add(data["session_id"])
+                _cleanup_grant(pending_file)
+                cleaned += 1
+
+    except Exception as e:
+        logger.error("Error during grant cleanup: %s", e)
+
+    for session_id in sessions_to_rebuild:
+        _rebuild_pending_index(session_id)
+
+    if cleaned:
+        logger.info("Cleaned up %d expired approval/pending files", cleaned)
+    return cleaned
+
+
+def get_pending_approvals_for_session(
+    session_id: Optional[str] = None,
+) -> List[Dict[str, Any]]:
+    """Return all non-expired pending approvals for a session.
+
+    Args:
+        session_id: Session ID to filter by (defaults to current session).
+
+    Returns:
+        List of pending approval dicts, newest first.
+    """
+    if session_id is None:
+        session_id = _get_session_id()
+
+    results: List[Dict[str, Any]] = []
+    try:
+        grants_dir = _get_grants_dir()
+        for pending_file in grants_dir.glob("pending-*.json"):
+            if pending_file.name.startswith("pending-index-"):
+                continue
+            data = _read_json_file(pending_file)
+            if not data or data.get("session_id") != session_id:
+                continue
+            if _is_rejected(data):
+                continue
+            timestamp = data.get("timestamp", 0)
+            ttl = data.get("ttl_minutes", DEFAULT_PENDING_TTL_MINUTES)
+            if _is_ttl_expired(float(timestamp), int(ttl)):
+                continue
+            results.append(data)
+    except Exception as e:
+        logger.error("Error listing pending approvals for session %s: %s", session_id, e)
+
+    results.sort(key=lambda d: d.get("timestamp", 0), reverse=True)
+    return results
+
+
+def find_pending_for_command(
+    session_id: str,
+    command: str,
+) -> Optional[str]:
+    """Find an existing pending approval nonce for this command and session.
+
+    When a subagent retries a blocked T3 command, a pending approval may
+    already exist from the first attempt.  Reusing the existing nonce
+    prevents the infinite-loop of generating a new approval_id on every
+    retry while the user is still reviewing the first one.
+
+    Args:
+        session_id: Session to search.
+        command: The command to match against pending approvals.
+
+    Returns:
+        The nonce (approval_id) if a matching pending approval exists, else None.
+    """
+    pending_list = get_pending_approvals_for_session(session_id)
+    if not pending_list:
+        return None
+
+    # Build a signature for the incoming command to compare semantically
+    target_sig = build_approval_signature(
+        command,
+        scope_type=SCOPE_SEMANTIC_SIGNATURE,
+    )
+    if target_sig is None:
+        return None
+
+    for pending_data in pending_list:
+        pending_sig_data = pending_data.get("scope_signature")
+        if not pending_sig_data:
+            continue
+        try:
+            pending_sig = ApprovalSignature.from_dict(pending_sig_data)
+            if matches_approval_signature(pending_sig, command):
+                nonce = pending_data.get("nonce")
+                if nonce:
+                    logger.info(
+                        "Reusing existing pending approval nonce=%s for command: %s",
+                        nonce, command[:80],
+                    )
+                    return nonce
+        except Exception:
+            continue
+
+    return None
+
+
+def reject_pending(nonce_prefix: str) -> bool:
+    """Mark a pending approval as rejected without deleting the file.
+
+    Finds the pending file whose nonce starts with ``nonce_prefix``, sets
+    ``status`` to ``"rejected"`` and ``rejected_at`` to the current time,
+    writes the file back, and rebuilds the session index.
+
+    Rejected pendings are invisible to all readers (``_is_rejected`` filter)
+    and are cleaned up by the pending scanner on its next sweep.
+
+    Args:
+        nonce_prefix: Hex prefix of the nonce (typically 8 chars from ``[P-xxx]``).
+
+    Returns:
+        True if a matching pending was found and rejected, False otherwise.
+    """
+    try:
+        grants_dir = _get_grants_dir()
+        for pending_file in grants_dir.glob("pending-*.json"):
+            if pending_file.name.startswith("pending-index-"):
+                continue
+            fname_nonce = pending_file.stem.removeprefix("pending-")
+            if not fname_nonce.startswith(nonce_prefix):
+                continue
+            data = _read_json_file(pending_file)
+            if not data or _is_rejected(data):
+                continue
+            data["status"] = "rejected"
+            data["rejected_at"] = time.time()
+            pending_file.write_text(json.dumps(data, indent=2))
+            session_id = data.get("session_id")
+            if session_id:
+                _rebuild_pending_index(session_id)
+            logger.info(
+                "Pending approval rejected: nonce_prefix=%s, nonce=%s",
+                nonce_prefix, data.get("nonce", "?"),
+            )
+            return True
+    except Exception as e:
+        logger.error("Error rejecting pending approval for prefix %s: %s", nonce_prefix, e)
+    return False
+
+
+def write_pending_approval_for_file(
+    nonce: str,
+    file_path: str,
+    session_id: Optional[str] = None,
+    ttl_minutes: int = DEFAULT_PENDING_TTL_MINUTES,
+    context: Optional[Dict[str, Any]] = None,
+) -> Optional[Path]:
+    """Write a pending approval file when a Write/Edit to a protected path is blocked.
+
+    Analogous to write_pending_approval() but uses SCOPE_FILE_PATH so that
+    the file path (not a shell command) is the scope identifier.
+
+    Args:
+        nonce: Cryptographic nonce from generate_nonce().
+        file_path: The absolute path of the file being written/edited.
+        session_id: Session ID (defaults to CLAUDE_SESSION_ID env var).
+        ttl_minutes: How long the pending approval is valid before expiry
+            (0 = no expiry).
+        context: Optional dict with enriched context (source, description,
+            risk, rollback, branch, files_changed, etc.).
+
+    Returns:
+        Path to the pending file, or None on failure.
+    """
+    if session_id is None:
+        session_id = _get_session_id()
+
+    signature = build_file_path_signature(file_path)
+    if signature is None:
+        logger.error(
+            "Failed to build file-path approval signature for pending file: %s",
+            file_path,
+        )
+        return None
+
+    pending_data = {
+        "nonce": nonce,
+        "session_id": session_id,
+        "command": file_path,
+        "danger_verb": "write",
+        "danger_category": "FILE_WRITE",
+        "scope_type": signature.scope_type,
+        "scope_signature": signature.to_dict(),
+        "timestamp": time.time(),
+        "ttl_minutes": ttl_minutes,
+        "context": context or {},
+    }
+
+    try:
+        grants_dir = _get_grants_dir()
+        pending_file = grants_dir / f"pending-{nonce}.json"
+        pending_file.write_text(json.dumps(pending_data, indent=2))
+        _rebuild_pending_index(session_id)
+
+        logger.info(
+            "Pending file-path approval written: nonce=%s, file=%s, session=%s",
+            nonce, file_path, session_id,
+        )
+        return pending_file
+
+    except Exception as e:
+        logger.error("Failed to write pending file-path approval: %s", e)
+        return None
+
+
+def check_approval_grant_for_file(
+    file_path: str,
+    session_id: str = None,
+) -> Optional[ApprovalGrant]:
+    """Check if there is an active approval grant for a Write/Edit file path.
+
+    Called by _adapt_write_edit before blocking a protected-path write. If
+    a valid SCOPE_FILE_PATH grant exists for this path, the write should be
+    allowed through.
+
+    Args:
+        file_path: The file path being written/edited.
+        session_id: Session ID for grant scoping (defaults to env var).
+
+    Returns:
+        The matching ApprovalGrant if found and valid, None otherwise.
+    """
+    if not session_id:
+        session_id = _get_session_id()
+
+    try:
+        grants_dir = _get_grants_dir()
+        if not grants_dir.exists():
+            return None
+
+        for grant_file in sorted(grants_dir.glob(f"grant-{session_id}-*.json")):
+            try:
+                data = json.loads(grant_file.read_text())
+                grant = ApprovalGrant(**data)
+
+                if not grant.is_valid():
+                    if grant.is_expired():
+                        _cleanup_grant(grant_file)
+                    continue
+
+                signature = grant.get_signature()
+                if signature is None or signature.scope_type != SCOPE_FILE_PATH:
+                    continue
+
+                if matches_file_path_approval(signature, file_path):
+                    logger.info(
+                        "File-path approval grant matched: file='%s', grant=%s",
+                        file_path, grant_file.name,
+                    )
+                    return grant
+
+            except (json.JSONDecodeError, TypeError) as e:
+                logger.warning("Invalid grant file %s: %s", grant_file, e)
+                _cleanup_grant(grant_file)
+                continue
+
+    except Exception as e:
+        logger.error("Error checking file-path approval grants: %s", e)
+
+    return None
+
+
+def find_pending_for_file(
+    session_id: str,
+    file_path: str,
+) -> Optional[str]:
+    """Find an existing pending approval nonce for this file path and session.
+
+    When a subagent retries a blocked Write/Edit, a pending approval may
+    already exist from the first attempt.  Reusing the existing nonce
+    prevents generating a new approval_id on every retry while the user
+    reviews the first one.
+
+    Args:
+        session_id: Session to search.
+        file_path: The file path to match against pending approvals.
+
+    Returns:
+        The nonce (approval_id) if a matching pending approval exists, else None.
+    """
+    pending_list = get_pending_approvals_for_session(session_id)
+    if not pending_list:
+        return None
+
+    stripped = file_path.strip() if file_path else ""
+    for pending_data in pending_list:
+        pending_sig_data = pending_data.get("scope_signature")
+        if not pending_sig_data:
+            continue
+        try:
+            pending_sig = ApprovalSignature.from_dict(pending_sig_data)
+            if matches_file_path_approval(pending_sig, stripped):
+                nonce = pending_data.get("nonce")
+                if nonce:
+                    logger.info(
+                        "Reusing existing pending file-path approval nonce=%s for file: %s",
+                        nonce, file_path,
+                    )
+                    return nonce
+        except Exception:
+            continue
+
+    return None
+
+
+def activate_grants_for_session(
+    session_id: Optional[str] = None,
+    ttl_minutes: int = DEFAULT_GRANT_TTL_MINUTES,
+) -> List[ApprovalActivationResult]:
+    """Activate ALL pending approvals for a session.
+
+    Called by the ElicitationResult hook when the user approves via
+    AskUserQuestion. Converts every non-expired pending approval for the
+    session into an active grant.
+
+    Args:
+        session_id: Session to activate for (defaults to current session).
+        ttl_minutes: TTL for the resulting active grants.
+
+    Returns:
+        List of activation results (one per pending approval).
+    """
+    if session_id is None:
+        session_id = _get_session_id()
+
+    pending_list = get_pending_approvals_for_session(session_id)
+    results: List[ApprovalActivationResult] = []
+
+    for pending_data in pending_list:
+        nonce = pending_data.get("nonce", "")
+        if not nonce:
+            continue
+        result = activate_pending_approval(
+            nonce=nonce,
+            session_id=session_id,
+            ttl_minutes=ttl_minutes,
+        )
+        results.append(result)
+        logger.info(
+            "Session-wide activation: nonce=%s status=%s",
+            nonce,
+            getattr(result.status, "value", str(result.status)),
+        )
+
+    return results
+
+
+# ============================================================================
+# Batch (Verb-Family) Grant Creation
+# ============================================================================
+
+DEFAULT_BATCH_TTL_MINUTES = 10
+
+
+def create_verb_family_grant(
+    session_id: str,
+    base_cmd: str,
+    verb: str,
+    danger_category: str = "",
+    ttl_minutes: int = DEFAULT_BATCH_TTL_MINUTES,
+) -> Optional[Path]:
+    """Create a multi-use SCOPE_VERB_FAMILY grant directly (no pending phase).
+
+    Called when the user approves a batch operation.  The resulting grant
+    matches any command with the same ``base_cmd`` and ``verb``, regardless
+    of arguments or non-dangerous flags, and is NOT consumed after a single
+    use.  It expires after ``ttl_minutes``.
+
+    Args:
+        session_id: The Claude session that owns this grant.
+        base_cmd: CLI base command (e.g., "gws", "kubectl").
+        verb: The mutative verb (e.g., "modify", "delete").
+        danger_category: Optional danger category for stricter matching.
+        ttl_minutes: Grant lifetime in minutes (default 10).
+
+    Returns:
+        Path to the grant file, or None on failure.
+    """
+    from .mutative_verbs import CATEGORY_UNKNOWN, CLI_FAMILY_LOOKUP
+
+    if not session_id or not base_cmd or not verb:
+        logger.error(
+            "create_verb_family_grant called with missing required args: "
+            "session_id=%s, base_cmd=%s, verb=%s",
+            session_id, base_cmd, verb,
+        )
+        return None
+
+    resolved_category = danger_category if danger_category else CATEGORY_UNKNOWN
+    cli_family = CLI_FAMILY_LOOKUP.get(base_cmd, "unknown")
+
+    signature = ApprovalSignature(
+        scope_type=SCOPE_VERB_FAMILY,
+        base_cmd=base_cmd,
+        cli_family=cli_family,
+        danger_category=resolved_category,
+        verb=verb.lower(),
+        # Intentionally empty -- verb_family matching ignores these:
+        semantic_tokens=(),
+        normalized_flags=(),
+        dangerous_flags=(),
+        exact_tokens=(),
+    )
+
+    grant = ApprovalGrant(
+        session_id=session_id,
+        approved_verbs=[verb.lower()],
+        approved_scope=f"batch:{base_cmd} {verb}",
+        scope_type=SCOPE_VERB_FAMILY,
+        scope_signature=signature.to_dict(),
+        granted_at=time.time(),
+        ttl_minutes=ttl_minutes,
+        used=False,
+        confirmed=False,
+        multi_use=True,
+    )
+
+    try:
+        grants_dir = _get_grants_dir()
+        grant_file = grants_dir / f"grant-{session_id}-batch-{int(time.time() * 1000)}.json"
+        grant_file.write_text(json.dumps(asdict(grant), indent=2))
+        logger.info(
+            "Verb-family batch grant created: base_cmd=%s, verb=%s, "
+            "ttl=%d min, session=%s, file=%s",
+            base_cmd, verb, ttl_minutes, session_id[:12], grant_file.name,
+        )
+        return grant_file
+
+    except Exception as e:
+        logger.error("Failed to create verb-family grant: %s", e)
+        return None
+
+
+def _cleanup_grant(grant_file: Path) -> None:
+    """Remove a single grant or pending file."""
+    try:
+        grant_file.unlink(missing_ok=True)
+    except Exception as e:
+        logger.warning("Failed to remove grant file %s: %s", grant_file, e)