@jaguilar87/gaia-ops 4.4.0 → 4.7.2

package/hooks/modules/events/event_writer.py

@@ -0,0 +1,210 @@
+"""Event writer and reader for the GAIA Event Context system.
+
+Provides:
+    - EventWriter: append-only JSONL writer with file locking
+    - read_events(): read events from last N hours with optional filtering
+    - cleanup_old_events(): remove events older than N days
+    - Event type constants
+"""
+
+import fcntl
+import json
+import logging
+import os
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..core.paths import get_events_dir
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Event type constants
+# ---------------------------------------------------------------------------
+
+AGENT_DISPATCH = "agent.dispatch"
+AGENT_COMPLETE = "agent.complete"
+COMMAND_EXECUTED = "command.executed"
+SESSION_END = "session.end"
+TRIGGER_SCHEDULED = "trigger.scheduled"
+HEARTBEAT = "heartbeat"
+USER_NOTE = "user.note"
+
+
+class EventWriter:
+    """Append-only JSONL event writer with file locking.
+
+    All writes are wrapped in try/except -- events are non-critical and
+    must never block the hook pipeline.
+    """
+
+    def __init__(self, events_dir: Optional[Path] = None):
+        self.events_dir = events_dir or get_events_dir()
+        self.events_file = self.events_dir / "events.jsonl"
+        self.lock_file = self.events_dir / "events.jsonl.lock"
+
+    def write_event(
+        self,
+        event_type: str,
+        source: str,
+        agent: str,
+        result: str,
+        severity: str = "info",
+        meta: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        """Append a single event to the JSONL log.
+
+        Thread-safe via exclusive file lock.  Fails silently on any error
+        to avoid disrupting the hook pipeline.
+
+        Args:
+            event_type: Dotted event category (e.g. "agent.dispatch").
+            source: Who wrote the event (e.g. "hook").
+            agent: Agent involved, or empty string for non-agent events.
+            result: Outcome summary string.
+            severity: info | warning | error.
+            meta: Optional type-specific structured data.
+        """
+        try:
+            self.events_dir.mkdir(parents=True, exist_ok=True)
+
+            record: Dict[str, Any] = {
+                "ts": datetime.now(timezone.utc).isoformat(),
+                "type": event_type,
+                "source": source,
+                "agent": agent,
+                "result": result,
+                "severity": severity,
+            }
+            if meta:
+                record["meta"] = meta
+
+            with open(self.lock_file, "w") as lf:
+                fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
+                try:
+                    with open(self.events_file, "a") as f:
+                        f.write(json.dumps(record, separators=(",", ":")) + "\n")
+                finally:
+                    fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
+
+        except Exception as exc:
+            logger.debug("Event write failed (non-fatal): %s", exc)
+
+
+def read_events(
+    hours: int = 24,
+    event_type: Optional[str] = None,
+    limit: int = 50,
+    events_dir: Optional[Path] = None,
+) -> List[Dict[str, Any]]:
+    """Read recent events from the JSONL log.
+
+    Args:
+        hours: How far back to look (default 24h).
+        event_type: Optional filter by event type (exact match).
+        limit: Maximum number of events to return.
+        events_dir: Override events directory (for testing).
+
+    Returns:
+        List of event dicts, most recent last, capped at *limit*.
+    """
+    try:
+        edir = events_dir or get_events_dir()
+        events_file = edir / "events.jsonl"
+        if not events_file.exists():
+            return []
+
+        cutoff = datetime.now(timezone.utc) - timedelta(hours=hours)
+        results: List[Dict[str, Any]] = []
+
+        with open(events_file, "r") as f:
+            for line in f:
+                line = line.strip()
+                if not line:
+                    continue
+                try:
+                    evt = json.loads(line)
+                except json.JSONDecodeError:
+                    continue
+
+                # Time filter
+                try:
+                    ts = datetime.fromisoformat(evt.get("ts", ""))
+                    if ts < cutoff:
+                        continue
+                except (ValueError, TypeError):
+                    continue
+
+                # Type filter
+                if event_type and evt.get("type") != event_type:
+                    continue
+
+                results.append(evt)
+
+        # Return the most recent events, capped at limit
+        return results[-limit:]
+
+    except Exception as exc:
+        logger.debug("Event read failed (non-fatal): %s", exc)
+        return []
+
+
+def cleanup_old_events(
+    days: int = 7,
+    events_dir: Optional[Path] = None,
+) -> int:
+    """Remove events older than *days* from the JSONL log.
+
+    Uses file locking to avoid conflicts with concurrent writers.
+    Retains lines that cannot be parsed (conservative).
+
+    Args:
+        days: Retention window in days (default 7).
+        events_dir: Override events directory (for testing).
+
+    Returns:
+        Number of events removed.
+    """
+    try:
+        edir = events_dir or get_events_dir()
+        events_file = edir / "events.jsonl"
+        lock_file = edir / "events.jsonl.lock"
+
+        if not events_file.exists():
+            return 0
+
+        retention_days = int(os.environ.get("GAIA_EVENT_RETENTION_DAYS", str(days)))
+        cutoff = datetime.now(timezone.utc) - timedelta(days=retention_days)
+        kept: List[str] = []
+        removed = 0
+
+        with open(lock_file, "w") as lf:
+            fcntl.flock(lf.fileno(), fcntl.LOCK_EX)
+            try:
+                with open(events_file, "r") as f:
+                    for line in f:
+                        line = line.strip()
+                        if not line:
+                            continue
+                        try:
+                            evt = json.loads(line)
+                            ts = datetime.fromisoformat(evt["ts"])
+                            if ts < cutoff:
+                                removed += 1
+                                continue
+                        except (json.JSONDecodeError, KeyError, ValueError):
+                            pass  # Keep unparseable lines
+                        kept.append(line)
+
+                with open(events_file, "w") as f:
+                    for line in kept:
+                        f.write(line + "\n")
+            finally:
+                fcntl.flock(lf.fileno(), fcntl.LOCK_UN)
+
+        return removed
+
+    except Exception as exc:
+        logger.debug("Event cleanup failed (non-fatal): %s", exc)
+        return 0

package/hooks/modules/identity/ops_identity.py

@@ -2,42 +2,33 @@
 
 
 def build_ops_identity() -> str:
-    """Build identity context for ops mode (full orchestrator).
-
-    Lightweight identity that delegates details to on-demand skills.
-    Always dispatches — never searches or executes directly.
-    """
     return """# Identity: Gaia Ops Orchestrator
 
-You are a dispatcher. Users bring requests; you determine which
-specialist agent can handle them and relay the work.
+You are a dispatcher. Users bring requests; you route to the right
+specialist agent. You never investigate or execute yourself.
 
 ## Your tools
-- **Agent** — dispatch work to specialist agents
-- **SendMessage** — resume a previously spawned agent with `to: agentId`
-- **AskUserQuestion** — get clarification or approval from the user
-- **Skill** — load on-demand procedures
+- **Agent** — dispatch to specialist agents
+- **SendMessage** — resume a previously spawned agent
+- **AskUserQuestion** — get clarification or approval
+- **Skill** — load on-demand procedures (agent-response, orchestrator-approval)
 
 ## Routing
 
-When the request is project-related (code, infrastructure, deployment,
-planning, or anything about this codebase), **always** load the
-project-dispatch skill — it has the agent table and dispatch rules.
-Do not search, explore, or run commands yourself. Dispatch to an agent.
+Each user message includes a routing recommendation. Follow it:
+- confidence >= 0.5 — dispatch the recommended agent(s) using the dispatch_mode
+- confidence < 0.5 — ask the user to clarify
+- no recommendation — respond directly (general question)
 
-When you receive an agent response with a `json:contract`, load the
-agent-response skill — it explains how to interpret each status
-and present results to the user.
+Your prompt to the agent = user's objective + info agent cannot derive.
+Resume an active agent with SendMessage instead of creating a new one.
 
-When it is a general question, reasoning, or you already have the
-answer from loaded context, respond directly.
+## Response Handling
 
-## Security
-- T3 operations are handled by agents through the nonce approval workflow
-- When you see AWAITING_APPROVAL, load the orchestrator-approval skill
-- Never synthesize nonces — they are hex tokens from the hook
+When an agent returns a json:contract, load agent-response skill.
+When an agent returns REVIEW with approval_id, load orchestrator-approval skill.
 
 ## Failures
-- If a hook blocks a command, relay the message verbatim. Do not try alternatives.
-- If routing is unclear, ask the user to clarify.
-- If an agent contradicts another, present both sides and let user decide."""
+- Hook blocks a command — relay message verbatim, no alternatives
+- Routing unclear — ask the user
+- Agents contradict — present both sides, user decides"""

package/hooks/modules/memory/episode_writer.py

@@ -6,7 +6,6 @@ session_state.py directly into this module.
 
 Provides:
     - write(): Store workflow as episodic memory
-    - capture_episodic_memory(): Backward-compatible alias for write()
     - get_session_events(): Read context.json, categorize events
 """
 
@@ -170,7 +169,7 @@ def write(
                 outcome = "failed"
                 success = False
             else:
-                # IN_PROGRESS, REVIEW, AWAITING_APPROVAL, NEEDS_INPUT -> partial
+                # IN_PROGRESS, REVIEW, NEEDS_INPUT -> partial
                 outcome = "partial"
                 success = None
         elif exit_code == 0:
@@ -226,7 +225,3 @@ def write(
     except Exception as e:
         logger.debug(f"Failed to capture episodic memory: {e}")
         return None
-
-
-# Backward-compatible alias
-capture_episodic_memory = write

package/hooks/modules/orchestrator/__init__.py

@@ -0,0 +1 @@
+# Orchestrator enforcement modules.

package/hooks/modules/orchestrator/delegate_mode.py

@@ -0,0 +1,128 @@
+"""Orchestrator delegate mode enforcement.
+
+When GAIA is installed, delegate mode is always active. The orchestrator
+(main session) is restricted to dispatch-only tools. Direct investigation
+tools (Bash, Read, Edit, etc.) are blocked so the orchestrator must
+delegate to specialist agents.
+
+Detection: Claude Code includes ``agent_id`` and ``agent_type`` in the
+PreToolUse payload ONLY when the hook fires inside a subagent. Their absence
+means the call originates from the main session (orchestrator).
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Tools the orchestrator is allowed to use in delegate mode.
+# Everything NOT in this set is blocked for the main session.
+ORCHESTRATOR_ALLOWED_TOOLS = frozenset({
+    # Dispatch and communication
+    "agent",
+    "task",
+    "sendmessage",
+
+    # On-demand skills / procedures
+    "skill",
+
+    # Agent teams task management
+    "taskcreate",
+    "taskupdate",
+    "tasklist",
+    "taskget",
+
+    # Tool discovery
+    "toolsearch",
+
+    # Web research (read-only, T0)
+    "websearch",
+    "webfetch",
+
+    # User interaction (built-in, may not always trigger hooks)
+    "askuserquestion",
+})
+
+
+@dataclass(frozen=True)
+class DelegateModeResult:
+    """Result of delegate mode check."""
+
+    blocked: bool
+    reason: Optional[str] = None
+
+
+def is_orchestrator_context(hook_payload: Dict[str, Any]) -> bool:
+    """Determine if the hook is firing in the main session (orchestrator).
+
+    Claude Code includes ``agent_id`` in the PreToolUse payload only when
+    the tool call originates from a subagent. Its absence means the call
+    is from the main session.
+
+    Args:
+        hook_payload: The full stdin JSON dict from Claude Code.
+
+    Returns:
+        True if this is the orchestrator (main session), False if subagent.
+    """
+    agent_id = hook_payload.get("agent_id")
+    # agent_id is absent or empty string for the main session
+    return not agent_id
+
+
+def check_delegate_mode(
+    tool_name: str, hook_payload: Dict[str, Any]
+) -> DelegateModeResult:
+    """Check whether a tool call should be blocked by delegate mode.
+
+    This is the single entry point. Call it early in the PreToolUse flow.
+
+    Args:
+        tool_name: The tool being invoked (e.g., "Bash", "Read", "Edit").
+        hook_payload: The full stdin JSON dict from Claude Code.
+
+    Returns:
+        DelegateModeResult with blocked=True and a reason if the call
+        should be denied, or blocked=False if it should proceed.
+    """
+    is_orchestrator = is_orchestrator_context(hook_payload)
+    if not is_orchestrator:
+        # Subagents have full tool access -- delegate mode does not apply
+        agent_id = hook_payload.get("agent_id", "<none>")
+        logger.debug(
+            "delegate_mode check: SKIP (subagent %s) tool=%s",
+            agent_id,
+            tool_name,
+        )
+        return DelegateModeResult(blocked=False)
+
+    normalized = tool_name.lower().strip()
+    if normalized in ORCHESTRATOR_ALLOWED_TOOLS:
+        logger.debug(
+            "delegate_mode check: ALLOW (orchestrator allowed tool) tool=%s",
+            tool_name,
+        )
+        return DelegateModeResult(blocked=False)
+
+    logger.warning(
+        "DELEGATE_MODE blocked tool '%s' for orchestrator (main session)",
+        tool_name,
+    )
+
+    return DelegateModeResult(
+        blocked=True,
+        reason=(
+            f"[DELEGATE MODE] Tool '{tool_name}' is not available to the orchestrator.\n\n"
+            f"As the orchestrator, you must delegate work to specialist agents.\n"
+            f"Use the Agent tool to dispatch to the appropriate agent, or use\n"
+            f"SendMessage to resume an existing agent.\n\n"
+            f"Allowed orchestrator tools: Agent, SendMessage, Skill, TaskCreate, "
+            f"TaskUpdate, TaskList, TaskGet, ToolSearch, WebSearch, WebFetch, "
+            f"AskUserQuestion.\n\n"
+            f"Do NOT attempt to use {tool_name} directly. Identify the right\n"
+            f"specialist agent and delegate the work."
+        ),
+    )

package/hooks/modules/security/__init__.py

@@ -4,9 +4,9 @@ Security module - Security tiers, blocked patterns, mutative verb detection.
 Provides:
 - tiers: SecurityTier enum and classification
 - blocked_commands: Permanently blocked pattern matching
-- mutative_verbs: Mutative verb detection (nonce-based approval)
+- mutative_verbs: Mutative verb detection (user approval workflow)
 - gitops_validator: kubectl/helm/flux validation
-- approval_constants: Canonical nonce approval token
+- approval_constants: Approval token patterns (legacy APPROVE: and ElicitationResult)
 - approval_grants: Time-limited T3 command passthrough after user approval
 """
 
@@ -32,7 +32,6 @@ from .approval_messages import (
     CANONICAL_APPROVAL_TOKEN_GUIDANCE,
     CANONICAL_APPROVAL_FORMAT_GUIDANCE,
     LATEST_BLOCKED_COMMAND_PHRASE,
-    AWAITING_APPROVAL_STATUS,
 )
 from .approval_scopes import (
     ApprovalSignature,
@@ -76,7 +75,6 @@ __all__ = [
     "CANONICAL_APPROVAL_TOKEN_GUIDANCE",
     "CANONICAL_APPROVAL_FORMAT_GUIDANCE",
     "LATEST_BLOCKED_COMMAND_PHRASE",
-    "AWAITING_APPROVAL_STATUS",
     "ApprovalSignature",
     "SCOPE_EXACT_COMMAND",
     "SCOPE_SEMANTIC_SIGNATURE",

package/hooks/modules/security/approval_constants.py

@@ -1,4 +1,8 @@
-"""Canonical nonce approval token and deprecated approval phrases for T3 operation resumes."""
+"""Approval token patterns and deprecated approval phrases for T3 operation resumes.
+
+The APPROVE: prefix is a legacy path (SendMessage-based nonce relay). The primary
+approval flow now uses ElicitationResult (AskUserQuestion -> user clicks Approve).
+"""
 
 import re