{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://genai-security-project.github.io/agent-control-standard/schema/v0.1.0/hooks/session-start.json",
  "title": "steps/sessionStart payload",
  "description": "Fires once at session initiation, before any other steps/* hook for the session_id. Establishes the session boundary, opens the receipt chain (the first ContextEntry has previous_hash=null), and lets Guardians attach session-level state (policy bundle selection, tenant routing, identity binding) before content-bearing hooks fire. All payload fields are OPTIONAL — the simplest valid invocation is an empty payload that just marks the session boundary. Required by paradigms that need an explicit session boundary marker (AARM cumulative-context, IBAC intent lock at session start) and recommended for any deployment that wants to attach session-level identity or policy state out-of-band from agentTrigger.",
  "type": "object",
  "properties": {
    "user_identity": {
      "type": "object",
      "description": "Authenticated principal initiating the session. Shape is platform-defined; typical fields shown.",
      "properties": {
        "user_id": { "type": "string" },
        "roles": { "type": "array", "items": { "type": "string" } },
        "authentication_method": { "type": "string" }
      }
    },
    "policy_mode": {
      "type": "string",
      "enum": ["strict", "moderate", "permissive"],
      "description": "Declared scope_mode for this session. If Intent is also established here (or later via agentTrigger), Intent.scope_mode MUST equal this value."
    },
    "intent": {
      "type": "object",
      "description": "Optional Intent established at session start. Same shape as Intent inside agentTrigger. When present, the Guardian MUST treat this as the canonical session Intent: any later agentTrigger that attempts to establish a different Intent MUST be rejected, and Intent.parsed MUST NOT be mutable except via the intent_extension mechanism in ask-details.json.",
      "properties": {
        "raw": { "type": "string" },
        "parsed": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "tool": { "type": "string" },
              "operation": { "type": "string" },
              "resource": { "type": "string" }
            }
          }
        },
        "parser_provenance": { "$ref": "../provenance.json" },
        "scope_mode": {
          "type": "string",
          "enum": ["strict", "moderate", "permissive"]
        }
      },
      "if": { "required": ["parsed"] },
      "then": { "required": ["parser_provenance"] }
    },
    "platform_context": {
      "type": "object",
      "description": "Optional platform-specific context for session initialization (e.g., browser session id, IDE workspace path, request origin URL).",
      "additionalProperties": true
    }
  }
}