Agent Hooks

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://agent-hooks.dev/schemas/v1/event.json",
  "title": "Agent Hooks Event",
  "type": "object",
  "required": ["spec_version", "event_id", "event_type", "timestamp", "source", "session_id"],  "properties": {
    "spec_version": {
      "type": "string",
      "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+$",
      "description": "Agent Hooks specification version (e.g., '0.1.0')"
    },
    "event_id": {
      "type": "string",
      "format": "uuid",
      "description": "Unique identifier for this event"
    },
    "event_type": {
      "type": "string",
      "description": "Unified event type using dot-separated Category.Subcategory format"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "RFC 3339 timestamp when event occurred"
    },
    "source": {
      "$ref": "#/$defs/source",
      "description": "The tool that emitted this event"
    },
    "session_id": {
      "type": "string",
      "description": "Identifier tying events to the same session"
    },
    "parent_session_id": {
      "type": "string",
      "description": "Parent session ID for nested or sub-agent sessions"
    },
    "user": {
      "$ref": "#/$defs/user",
      "description": "The human who initiated the agent session"
    },
    "actor": {
      "$ref": "#/$defs/actor",
      "description": "The entity that triggered this specific event"
    },
    "agent_mode": {
      "type": "string",
      "enum": ["agent", "plan", "execute", "chat", "edit"],
      "description": "The mode the agent was operating in"    },
    "data": {
      "type": "object",
      "description": "Event-type-specific payload"
    },
    "risk": {
      "$ref": "#/$defs/risk",
      "description": "Risk assessment for this event"
    },
    "metadata": {
      "type": "object",
      "description": "Vendor-specific or implementation-specific data"
    }
  },
  "$defs": {
    "source": {
      "type": "object",
      "required": ["tool"],
      "properties": {
        "tool": {
          "type": "string",
          "description": "Tool name (e.g., 'cursor', 'claude-code', 'gemini-cli', 'copilot', 'windsurf')"
        },
        "version": {
          "type": "string",
          "description": "Tool version"
        }
      }
    },
    "user": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "User identifier (email, username, or UUID)"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "actor": {
      "type": "object",
      "required": ["type"],      "properties": {
        "type": {
          "type": "string",
          "enum": ["user", "ai_agent", "system"]
        },
        "id": {
          "type": "string",
          "description": "Actor identifier"
        },
        "name": {
          "type": "string"
        }
      }
    },
    "risk": {
      "type": "object",
      "properties": {
        "score": {
          "type": "integer",
          "minimum": 0,
          "maximum": 100,
          "description": "Numeric risk score (0 = no risk, 100 = critical)"
        },
        "level": {
          "type": "string",
          "enum": ["low", "medium", "high", "critical"],
          "description": "Categorical risk label"
        },
        "factors": {
          "type": "array",
          "items": { "type": "string" },
          "description": "Tags explaining why the risk was scored (e.g., 'SECRET_PATTERN', 'DESTRUCTIVE_OP')"
        }
      }
    },
    "action": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "Standardized action name (e.g., 'shell', 'read_file', 'write_file', 'mcp:<tool>')"
        },
        "input": {          "type": "object",
          "description": "Structured parameters for the action"
        },
        "result": {
          "type": "object",
          "properties": {
            "success": { "type": "boolean" },
            "exit_code": { "type": "integer" },
            "error_message": { "type": "string" },
            "output": { "type": "string", "description": "Truncated or summarized output" }
          }
        }
      }
    },
    "decision": {
      "type": "object",
      "properties": {
        "outcome": {
          "type": "string",
          "enum": ["allow", "deny", "ask"],
          "description": "Hook decision outcome"
        },
        "reason": {
          "type": "string",
          "description": "Human-readable reason for the decision"
        }
      }
    },
    "context": {
      "type": "object",
      "properties": {
        "trigger": {
          "type": "string",
          "enum": ["auto", "manual", "system"],
          "description": "What triggered the context operation"
        },
        "tokens_used": {
          "type": "integer",
          "description": "Current token count in use"
        },
        "tokens_limit": {
          "type": "integer",
          "description": "Maximum token limit before compaction triggers"
        },        "percentage_used": {
          "type": "number",
          "minimum": 0,
          "maximum": 100,
          "description": "Percentage of context window consumed (tokens_used / tokens_limit * 100)"
        },
        "tokens_before": {
          "type": "integer",
          "description": "Token count before compaction"
        },
        "tokens_after": {
          "type": "integer",
          "description": "Token count after compaction"
        },
        "tokens_removed": {
          "type": "integer"
        }
      }
    },
    "model": {
      "type": "object",
      "properties": {
        "model_id": {
          "type": "string",
          "description": "Model identifier following provider/model convention (e.g., 'anthropic/claude-sonnet-4-20250514')"
        },
        "input_tokens": { "type": "integer" },
        "output_tokens": { "type": "integer" },
        "latency_ms": { "type": "integer" },
        "retry_count": { "type": "integer" }
      }
    }
  }
}