@jaguilar87/gaia 5.0.0-rc1

package/dist/gaia-ops/tools/validation/validate_skills.py

@@ -0,0 +1,189 @@
+#!/usr/bin/env python3
+import os
+import re
+import yaml
+from pathlib import Path
+from collections import defaultdict
+
+def find_skills(base_dirs):
+    """Encuentra todas las skills en los directorios base."""
+    skills = {}
+    for base_dir in base_dirs:
+        path = Path(base_dir)
+        if not path.exists():
+            continue
+        for skill_file in path.rglob("SKILL.md"):
+            skill_name = skill_file.parent.name
+            skills[skill_name] = {
+                "path": str(skill_file),
+                "content": skill_file.read_text(encoding="utf-8", errors="ignore")
+            }
+    return skills
+
+def validate_skill_format(skills):
+    """Valida el formato de cada skill."""
+    validation_results = {}
+    for name, data in skills.items():
+        content = data["content"]
+        has_title = bool(re.search(r'^#\s+.+', content, re.MULTILINE))
+        validation_results[name] = {
+            "has_title": has_title,
+            "is_empty": len(content.strip()) == 0,
+            "path": data["path"]
+        }
+    return validation_results
+
+def find_agents(base_dirs):
+    """Encuentra las definiciones de los agentes."""
+    agents = {}
+    for base_dir in base_dirs:
+        path = Path(base_dir)
+        if not path.exists():
+            continue
+        for agent_file in path.rglob("*.md"):
+            if agent_file.name == "README.md":
+                continue
+            content = agent_file.read_text(encoding="utf-8", errors="ignore")
+            # Extraer frontmatter YAML
+            match = re.match(r'^---\s*\n(.*?)\n---\s*\n(.*)', content, re.DOTALL)
+            if match:
+                try:
+                    frontmatter = yaml.safe_load(match.group(1))
+                    if isinstance(frontmatter, dict) and "name" in frontmatter:
+                        agents[frontmatter["name"]] = {
+                            "path": str(agent_file),
+                            "skills_declared": frontmatter.get("skills", []),
+                            "body": match.group(2)
+                        }
+                except yaml.YAMLError:
+                    pass
+    return agents
+
+def analyze_injection():
+    """Analiza cómo se inyectan las skills (revisando pre_tool_use.py)."""
+    hook_path = Path("gaia-ops/hooks/pre_tool_use.py")
+    if not hook_path.exists():
+        return "No se encontró gaia-ops/hooks/pre_tool_use.py"
+    
+    content = hook_path.read_text(encoding="utf-8", errors="ignore")
+    if "skills are injected natively by Claude Code" in content:
+        return "Las skills se inyectan de forma nativa por Claude Code a través del campo 'skills:' en el frontmatter del agente (según pre_tool_use.py)."
+    return "Mecanismo de inyección en pre_tool_use.py analizado, pero no se encontró la nota estándar sobre inyección nativa."
+
+def generate_report(skills, validation, agents, injection_info):
+    """Genera el reporte en formato Markdown."""
+    report = ["# Reporte de Validación de Skills\n"]
+    
+    report.append("## 1. Análisis de Inyección")
+    report.append(f"{injection_info}\n")
+    
+    report.append(f"## 2. Skills Encontradas ({len(skills)})")
+    for name, val in validation.items():
+        status = "✅ OK" if val["has_title"] and not val["is_empty"] else "❌ PROBLEMA"
+        issues = []
+        if not val["has_title"]: issues.append("Falta título (# Título)")
+        if val["is_empty"]: issues.append("Archivo vacío")
+        issue_str = f" - Detalles: {', '.join(issues)}" if issues else ""
+        report.append(f"- **{name}** ({val['path']}): {status}{issue_str}")
+    report.append("")
+    
+    # Analizar uso de skills
+    used_skills = defaultdict(list)
+    missing_skills = defaultdict(list)
+    body_mentions = defaultdict(list)
+    
+    for agent_name, agent_data in agents.items():
+        declared = agent_data["skills_declared"] or []
+        body = agent_data["body"]
+        for skill in declared:
+            if skill in skills:
+                used_skills[skill].append(agent_name)
+            else:
+                missing_skills[agent_name].append(skill)
+        
+        # Check for skills mentioned in the body but not declared
+        for skill in skills:
+            if skill not in declared and skill in body:
+                body_mentions[agent_name].append(skill)
+                
+    report.append("## 3. Uso de Skills por Agentes")
+    if not agents:
+        report.append("No se encontraron definiciones de agentes con frontmatter YAML válido.\n")
+    else:
+        for agent_name, agent_data in agents.items():
+            declared = agent_data["skills_declared"] or []
+            mentions = body_mentions[agent_name]
+            mention_str = f" (Menciona en texto sin declarar: {', '.join(mentions)})" if mentions else ""
+            report.append(f"- **{agent_name}**: {len(declared)} skills declaradas.{mention_str}")
+        report.append("")
+        
+    report.append("## 4. Gaps Identificados")
+    
+    # Skills no utilizadas
+    # Consideramos una skill como utilizada si está declarada o si se menciona explícitamente en el cuerpo
+    all_used_skills = set(used_skills.keys())
+    for mentions in body_mentions.values():
+        all_used_skills.update(mentions)
+        
+    unused_skills = set(skills.keys()) - all_used_skills
+    if unused_skills:
+        report.append("### Skills no utilizadas (Huérfanas)")
+        for skill in sorted(unused_skills):
+            report.append(f"- {skill}")
+    else:
+        report.append("### Skills no utilizadas (Huérfanas)")
+        report.append("- Ninguna. Todas las skills encontradas están asignadas a al menos un agente.")
+    report.append("")
+    
+    # Skills declaradas pero inexistentes
+    if missing_skills:
+        report.append("### Skills declaradas pero no encontradas (Faltantes)")
+        for agent, missing in missing_skills.items():
+            for m in missing:
+                report.append(f"- El agente **{agent}** declara la skill '{m}', pero no se encontró el archivo SKILL.md correspondiente.")
+    else:
+        report.append("### Skills declaradas pero no encontradas (Faltantes)")
+        report.append("- Ninguna. Todas las skills declaradas por los agentes existen.")
+    report.append("")
+    
+    # Skills mencionadas en el texto pero no inyectadas formalmente
+    report.append("### Skills mencionadas en el texto pero NO declaradas en 'skills:'")
+    if body_mentions:
+        for agent, mentions in body_mentions.items():
+            for m in mentions:
+                report.append(f"- **{agent}** menciona '{m}' en su cuerpo pero no está en la lista de inyección.")
+    else:
+        report.append("- Ninguna.")
+    report.append("")
+    
+    return "\n".join(report)
+
+def main():
+    skill_dirs = ["gaia-ops/skills", ".claude/skills", "conductor-orchestrator/skills"]
+    agent_dirs = ["gaia-ops/agents", ".claude/agents", "conductor-orchestrator/agents"]
+    
+    print("Buscando skills...")
+    skills = find_skills(skill_dirs)
+    
+    print("Validando formato...")
+    validation = validate_skill_format(skills)
+    
+    print("Buscando agentes...")
+    agents = find_agents(agent_dirs)
+    
+    print("Analizando inyección...")
+    injection_info = analyze_injection()
+    
+    print("Generando reporte...")
+    report = generate_report(skills, validation, agents, injection_info)
+    
+    report_path = Path("gaia-ops/tools/validation/skills_report.md")
+    report_path.write_text(report, encoding="utf-8")
+    print(f"Reporte generado en {report_path}")
+    
+    # Imprimir el reporte en la salida estándar para que el agente lo pueda devolver
+    print("\n" + "="*50 + "\n")
+    print(report)
+
+if __name__ == "__main__":
+    main()

package/dist/gaia-security/.claude-plugin/plugin.json

@@ -0,0 +1,24 @@
+{
+  "name": "gaia-security",
+  "version": "5.0.0-rc1",
+  "description": "Keeps you in the loop only when it matters. Gaia Security analyzes every command and classifies it into risk tiers: read-only queries run freely, simulations and validations pass through, and state-changing operations (create, delete, apply, push) pause for your explicit approval before executing. Irreversible commands like dropping databases or deleting cloud infrastructure are permanently blocked.",
+  "author": {
+    "name": "jaguilar87",
+    "email": "jorge.aguilar87@gmail.com"
+  },
+  "homepage": "https://github.com/metraton/gaia-ops#gaia-security",
+  "repository": "https://github.com/metraton/gaia-ops",
+  "license": "MIT",
+  "keywords": [
+    "security",
+    "devops"
+  ],
+  "engines": {
+    "claude-code": ">=2.1.0"
+  },
+  "categories": [
+    "devops",
+    "security",
+    "orchestration"
+  ]
+}

package/dist/gaia-security/README.md

@@ -0,0 +1,90 @@
+# gaia-security
+
+Keeps you in the loop only when it matters. Gaia Security analyzes every Bash command and classifies it into four risk tiers: read-only runs freely, validation and simulation pass through, state-changing operations (create, delete, apply, push) pause for explicit approval, and irreversible commands (database drops, cluster deletes, `git push --force`, `mkfs`, `dd`) are permanently blocked.
+
+Install this plugin when you want Gaia's security pipeline without the agent roster, skills, or orchestrator. It is the stripped-down path — hooks, modules, and the deny list. If you want the full Gaia experience with eight specialist agents and a planner, install `gaia-ops` instead.
+
+## Install
+
+**Via Claude Code marketplace:**
+
+```
+/plugin marketplace add metraton/gaia
+/plugin install gaia-security
+```
+
+**Via npm (standalone dist):**
+
+```bash
+npm install @jaguilar87/gaia
+# Then point Claude Code at dist/gaia-security/ in your settings.
+```
+
+## Quick start
+
+Once installed, the hooks activate automatically on session start. Try any of these to see the pipeline in action:
+
+```bash
+# Safe (T0) — runs directly
+ls -la
+
+# Validation (T1) — runs directly
+terraform validate
+
+# Simulation (T2) — runs directly
+terraform plan
+
+# Mutative (T3) — prompts for approval
+terraform apply
+
+# Blocked — permanently denied, no prompt
+gcloud sql instances delete my-prod-db
+```
+
+To manage approvals during a session:
+
+```
+# Inside Claude Code
+aprobar            # show pending approvals
+approve P-<id>     # grant a pending request
+reject P-<id>      # deny a pending request
+```
+
+## What ships with this plugin
+
+**Hooks** (5 lifecycle events): `PreToolUse`, `PostToolUse`, `UserPromptSubmit`, `SessionStart`, `Stop`. All wired to the same security pipeline that powers the full gaia-ops plugin.
+
+**Hook modules** (under `hooks/modules/`):
+
+- `core/` — classification logic, tier assignment
+- `security/` — blocked commands, mutative verb detection, nonce issuance
+- `audit/` — session registry, approval persistence
+- `tools/` — Bash, Edit, Write adapters
+- `validation/` — schema checks, permission validation
+- `identity/`, `context/`, `scanning/`, `session/`, `memory/`, `orchestrator/`, `events/` — supporting concerns
+- `adapters/claude_code.py` — bridges Gaia classification to CC native permission model
+
+**No agents. No skills. No commands.** This plugin is hooks + deny list by design.
+
+**Config**: `config/universal-rules.json` — shared rule set that governs tier classification.
+
+## Permissions
+
+- `Bash(*)` allowed — the pre-tool-use hook is the real security gate.
+- `Read`, `Glob`, `Grep`, `BashOutput`, `KillShell` allowed for inspection.
+- 45 irreversible commands permanently denied in `settings.json` (AWS VPC/RDS/S3 deletes, GCP project/cluster/SQL deletes, Kubernetes namespace/node/PV deletes, `git push --force`, `dd`, `mkfs`).
+
+Writes to `.claude/hooks/` and `.claude/settings*.json` are hook-protected — approval required even in `bypassPermissions` mode.
+
+## Troubleshooting
+
+- **Hook not firing**: confirm `hooks/hooks.json` is present and every `entries` file resolves on disk. Missing files are silently skipped.
+- **Approval flow stuck**: check `~/.claude/logs/` for hook traces; `aprobar` lists pending requests.
+- **Want the full system**: install `gaia-ops` — same hook pipeline, plus eight agents, skills, and the orchestrator.
+
+## Links
+
+- Documentation: [github.com/metraton/gaia#gaia-security](https://github.com/metraton/gaia#gaia-security)
+- Security policy: [SECURITY.md](https://github.com/metraton/gaia/blob/main/SECURITY.md)
+- Issues: [github.com/metraton/gaia/issues](https://github.com/metraton/gaia/issues)
+- License: MIT

package/dist/gaia-security/config/universal-rules.json

@@ -0,0 +1,102 @@
+{
+  "rules": {
+    "universal": [
+      {
+        "rule": "Your prompt includes a Project Context section with confirmed project knowledge. Extract relevant data from it BEFORE executing commands."
+      },
+      {
+        "rule": "context_map: The Project Context section is organized into named sections (e.g. project_identity, stack, git, infrastructure). Each section contains data scanned from the project. Reading the wrong section wastes tokens and produces stale assumptions; reading none at all causes commands built on defaults to fail in ways that are hard to trace back to the root cause."
+      }
+    ],
+    "agent_specific": {
+      "cloud-troubleshooter": {
+        "rules": [
+          {
+            "rule": "monitoring_observability and cluster_details are the primary diagnostic surfaces. A diagnosis that skips these sections will miss the live state of the cluster and produce recommendations that contradict what is already deployed."
+          },
+          {
+            "rule": "infrastructure_topology describes how services are connected across regions and availability zones. Ignoring it when investigating connectivity or latency issues leads to remediation steps that address symptoms rather than the structural cause."
+          },
+          {
+            "rule": "operational_guidelines encodes team conventions for runbooks, escalation paths, and SLOs. Bypassing it risks proposing changes that violate on-call agreements or SLA boundaries."
+          }
+        ]
+      },
+      "gitops-operator": {
+        "rules": [
+          {
+            "rule": "gitops_configuration holds the source-of-truth for Flux/ArgoCD sync targets, kustomize overlays, and reconciliation intervals. Writing manifests without reading this section produces changes that the GitOps controller will override or reject on the next sync cycle."
+          },
+          {
+            "rule": "cluster_details defines the Kubernetes version, node pools, and namespacing conventions. A manifest targeting the wrong API version or namespace will apply cleanly and then fail at runtime, making the error hard to attribute."
+          },
+          {
+            "rule": "operational_guidelines specifies change-window and approval policies. Bypassing it risks triggering a sync during a protected window and causing a production incident."
+          }
+        ]
+      },
+      "terraform-architect": {
+        "rules": [
+          {
+            "rule": "terraform_infrastructure contains existing module versions, backend configuration, and remote state references. Planning without this data generates a diff that replaces instead of updates, and can destroy live resources that were not in scope."
+          },
+          {
+            "rule": "infrastructure_topology maps provider accounts, VPCs, and cross-account trust relationships. Missing this context leads to resource definitions that introduce duplicate CIDR blocks or broken IAM trust chains."
+          },
+          {
+            "rule": "operational_guidelines captures cost-center tagging requirements and provider version constraints. Ignoring them produces plans that pass validation but are rejected at code review or fail cost attribution."
+          }
+        ]
+      },
+      "developer": {
+        "rules": [
+          {
+            "rule": "stack defines the languages, frameworks, and build tools in use. Writing code against a different stack version or framework than what is declared here produces changes that pass local tests and break in CI."
+          },
+          {
+            "rule": "application_services describes service boundaries, ports, and inter-service contracts. Changing a service's interface without consulting this section breaks consumers that are not under active development and not visible in the immediate file context."
+          },
+          {
+            "rule": "operational_guidelines specifies coding standards, test coverage thresholds, and linting rules. Code that meets the functional requirement but ignores these standards will be rejected at the review gate, requiring a rework cycle."
+          }
+        ]
+      },
+      "gaia-planner": {
+        "rules": [
+          {
+            "rule": "architecture_overview describes the current system design and known constraints. A plan that ignores these constraints will produce tasks that are technically coherent but architecturally incompatible with the existing system, requiring replanning after the first implementation attempt."
+          },
+          {
+            "rule": "application_services lists live services and their owners. Omitting this context leads to plans that assume capabilities are missing when they already exist, or that schedule work in the wrong order relative to service dependencies."
+          },
+          {
+            "rule": "operational_guidelines records process constraints such as deployment windows and team capacity limits. A plan that ignores them will hit blockers during execution that were predictable at planning time."
+          }
+        ]
+      },
+      "gaia-operator": {
+        "rules": [
+          {
+            "rule": "workspace_repos is this agent's primary surface: it lists every repository in the workspace with its path, platform, and role. Operating on a repo that is absent from this list risks working in the wrong directory or missing the canonical remote URL, causing pushes to fail or go to the wrong origin."
+          },
+          {
+            "rule": "git describes the platform, default branch, and branching strategy. Ignoring it produces branch names or merge strategies that conflict with the project's CI configuration and require manual cleanup."
+          }
+        ]
+      },
+      "gaia-system": {
+        "rules": [
+          {
+            "rule": "architecture_overview is the write target for system-level changes: updates made without first reading the current state overwrite accurate data with stale assumptions, corrupting the context that all other agents depend on."
+          },
+          {
+            "rule": "operational_guidelines captures team-agreed constraints on the Gaia system itself. Proposing architectural changes that contradict these guidelines produces recommendations that will be rejected and mislead agents that read the context between now and the rejection."
+          },
+          {
+            "rule": "infrastructure provides the deployment environment for Gaia components. Missing this section leads to skill or hook designs that assume capabilities (e.g. network access, file system layout) that do not exist in the actual runtime environment."
+          }
+        ]
+      }
+    }
+  }
+}

package/dist/gaia-security/hooks/adapters/__init__.py

@@ -0,0 +1,52 @@
+"""
+Adapter Layer for Gaia-Ops Hooks.
+
+Provides CLI-agnostic normalized types and the abstract HookAdapter interface.
+Business logic modules consume and produce these types; concrete adapters
+translate between these types and CLI-specific JSON protocols.
+
+Modules:
+- types: Frozen dataclasses and enums for all hook event/response data
+- base: Abstract HookAdapter interface
+"""
+
+from .types import (
+    HookEventType,
+    PermissionDecision,
+    DistributionChannel,
+    HookEvent,
+    ValidationRequest,
+    ValidationResult,
+    ToolResult,
+    AgentCompletion,
+    CompletionResult,
+    ContextResult,
+    BootstrapResult,
+    QualityResult,
+    VerificationResult,
+    HookResponse,
+)
+from .base import HookAdapter
+from .claude_code import ClaudeCodeAdapter
+from .utils import has_stdin_data, warn_if_dual_channel
+
+__all__ = [
+    "HookEventType",
+    "PermissionDecision",
+    "DistributionChannel",
+    "HookEvent",
+    "ValidationRequest",
+    "ValidationResult",
+    "ToolResult",
+    "AgentCompletion",
+    "CompletionResult",
+    "ContextResult",
+    "BootstrapResult",
+    "QualityResult",
+    "VerificationResult",
+    "HookResponse",
+    "HookAdapter",
+    "ClaudeCodeAdapter",
+    "has_stdin_data",
+    "warn_if_dual_channel",
+]

package/dist/gaia-security/hooks/adapters/base.py

@@ -0,0 +1,219 @@
+"""
+Abstract base class defining the adapter contract.
+
+Each CLI backend (Claude Code, future CLIs) provides a concrete implementation
+of HookAdapter. Business logic modules interact only with the normalized types;
+they never see raw CLI JSON.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+
+from .types import (
+    AgentCompletion,
+    BootstrapResult,
+    CompletionResult,
+    ContextResult,
+    DistributionChannel,
+    HookEvent,
+    HookResponse,
+    QualityResult,
+    ValidationResult,
+    VerificationResult,
+)
+
+
+class HookAdapter(ABC):
+    """Abstract adapter between CLI-specific JSON and normalized types.
+
+    Invariants (from adapter-interface contract):
+    1. Business logic modules NEVER see HookResponse.
+    2. The adapter NEVER modifies business logic results -- only translates format.
+    3. Adding a new hook event requires ONLY a new adapter method.
+    """
+
+    @abstractmethod
+    def parse_event(self, stdin_data: str) -> HookEvent:
+        """Parse raw stdin JSON into a normalized HookEvent.
+
+        Preconditions:
+            - stdin_data is a valid JSON string
+            - JSON contains at minimum: hook_event_name, session_id
+
+        Postconditions:
+            - Returns HookEvent with event_type set to a valid HookEventType
+            - Returns HookEvent with session_id populated
+            - payload contains the full raw event data
+
+        Raises:
+            ValueError: If JSON is invalid or event type is unknown.
+        """
+        ...
+
+    @abstractmethod
+    def format_validation_response(self, result: ValidationResult) -> HookResponse:
+        """Format a ValidationResult for CLI consumption.
+
+        Preconditions:
+            - result.allowed is a valid boolean
+            - result.reason is a non-empty string
+
+        Postconditions:
+            - HookResponse.output is a valid JSON-serializable dict
+            - HookResponse.exit_code is 0 (corrective deny) or 2 (permanent block)
+            - If result.allowed is True, output contains permissionDecision: allow
+            - If result.allowed is False, output contains permissionDecision: deny
+            - If result.modified_input is set, output contains updatedInput
+        """
+        ...
+
+    @abstractmethod
+    def format_completion_response(self, result: CompletionResult) -> HookResponse:
+        """Format a CompletionResult for CLI consumption.
+
+        Postconditions:
+            - HookResponse.output contains contract_valid, anomalies_detected
+            - HookResponse.exit_code is always 0
+        """
+        ...
+
+    @abstractmethod
+    def format_context_response(self, result: ContextResult) -> HookResponse:
+        """Format a ContextResult for CLI consumption."""
+        ...
+
+    @abstractmethod
+    def format_bootstrap_response(self, result: BootstrapResult) -> HookResponse:
+        """Format a BootstrapResult for CLI consumption.
+
+        Returns session bootstrap status for SessionStart events.
+        """
+        ...
+
+    @abstractmethod
+    def adapt_session_start(self, raw: dict) -> BootstrapResult:
+        """Parse SessionStart event and return bootstrap actions.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a SessionStart event
+
+        Postconditions:
+            - Returns BootstrapResult with should_scan and should_refresh set
+              based on session_type
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    # P2 event adapters
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def adapt_stop(self, raw: dict) -> QualityResult:
+        """Parse Stop event and assess response quality.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a Stop event
+
+        Postconditions:
+            - Returns QualityResult with quality assessment
+        """
+        ...
+
+    @abstractmethod
+    def adapt_task_completed(self, raw: dict) -> VerificationResult:
+        """Parse TaskCompleted event and verify completion criteria.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a TaskCompleted event
+
+        Postconditions:
+            - Returns VerificationResult with criteria assessment
+        """
+        ...
+
+    @abstractmethod
+    def adapt_subagent_start(self, raw: dict) -> ContextResult:
+        """Parse SubagentStart event and prepare agent context.
+
+        Preconditions:
+            - raw is the HookEvent.payload dict for a SubagentStart event
+
+        Postconditions:
+            - Returns ContextResult with agent-specific context
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    # P2 formatters
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def format_quality_response(self, result: QualityResult) -> HookResponse:
+        """Format a QualityResult for CLI consumption."""
+        ...
+
+    @abstractmethod
+    def format_verification_response(self, result: VerificationResult) -> HookResponse:
+        """Format a VerificationResult for CLI consumption."""
+        ...
+
+    @abstractmethod
+    def detect_channel(self) -> DistributionChannel:
+        """Detect the distribution channel (NPM or PLUGIN).
+
+        Checks environment variables and filesystem layout to determine
+        how gaia-ops was installed.
+        """
+        ...
+
+    # ------------------------------------------------------------------ #
+    # Full hook lifecycle adapters (thin-gate pattern)
+    # ------------------------------------------------------------------ #
+
+    @abstractmethod
+    def adapt_pre_tool_use(self, event: HookEvent) -> HookResponse:
+        """Run all pre-tool-use business logic and return a formatted response.
+
+        Orchestrates: routing (bash vs task), validation, state management,
+        context injection, approval handling, and response formatting.
+
+        Preconditions:
+            - event is a parsed HookEvent with event_type PRE_TOOL_USE
+
+        Postconditions:
+            - Returns HookResponse ready for stdout + sys.exit()
+        """
+        ...
+
+    @abstractmethod
+    def adapt_post_tool_use(self, event: HookEvent) -> HookResponse:
+        """Run all post-tool-use business logic and return a formatted response.
+
+        Orchestrates: state retrieval, duration computation, audit logging,
+        T3 grant confirmation, critical event detection, session context
+        writing, and state cleanup.
+
+        Preconditions:
+            - event is a parsed HookEvent with event_type POST_TOOL_USE
+
+        Postconditions:
+            - Returns HookResponse (always exit 0, post-hook never blocks)
+        """
+        ...
+
+    @abstractmethod
+    def adapt_subagent_stop(self, event: HookEvent) -> HookResponse:
+        """Run all subagent-stop business logic and return a formatted response.
+
+        Orchestrates: contract parsing and validation, approval cleanup,
+        context updates, workflow recording, response contract validation,
+        anomaly detection, episodic memory, and result assembly.
+
+        Preconditions:
+            - event is a parsed HookEvent with event_type SUBAGENT_STOP
+
+        Postconditions:
+            - Returns HookResponse (exit 0 for success, exit 2 for contract rejection)
+        """
+        ...