{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://json.schemastore.org/codex-hooks.json",
  "title": "Codex hooks configuration",
  "description": "Configuration for OpenAI Codex lifecycle hooks.\nhttps://developers.openai.com/codex/hooks",
  "type": "object",
  "required": ["hooks"],
  "additionalProperties": false,
  "properties": {
    "hooks": {
      "type": "object",
      "description": "Hook event registrations grouped by Codex lifecycle event.",
      "minProperties": 1,
      "additionalProperties": {
        "$ref": "#/definitions/matcherGroups"
      },
      "properties": {
        "SessionStart": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs when a Codex session starts. The matcher filters the start source, such as startup, resume, or clear."
        },
        "PreToolUse": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs before supported tool calls. The matcher filters tool names and aliases."
        },
        "PermissionRequest": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs before Codex asks for approval. The matcher filters tool names and aliases."
        },
        "PostToolUse": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs after supported tool calls. The matcher filters tool names and aliases."
        },
        "PreCompact": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs before conversation compaction. The matcher filters the compaction trigger, such as manual or auto."
        },
        "PostCompact": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs after conversation compaction. The matcher filters the compaction trigger, such as manual or auto."
        },
        "UserPromptSubmit": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs before a user prompt is submitted. Codex currently ignores matcher for this event."
        },
        "SubagentStart": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs when a subagent starts. The matcher filters the subagent type."
        },
        "SubagentStop": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs when a subagent stops. The matcher filters the subagent type."
        },
        "Stop": {
          "$ref": "#/definitions/matcherGroups",
          "description": "Runs when a turn stops. Codex currently ignores matcher for this event."
        }
      }
    }
  },
  "definitions": {
    "matcherGroups": {
      "type": "array",
      "description": "Matcher groups for one Codex hook event.",
      "minItems": 1,
      "items": {
        "$ref": "#/definitions/matcherGroup"
      }
    },
    "matcherGroup": {
      "type": "object",
      "description": "Matcher group that decides when one or more hook handlers run.",
      "required": ["hooks"],
      "additionalProperties": true,
      "properties": {
        "matcher": {
          "type": "string",
          "description": "Regex string that filters when hooks fire. Use *, an empty string, or omit matcher to match every supported occurrence."
        },
        "hooks": {
          "type": "array",
          "description": "Handlers to run when this matcher group matches.",
          "minItems": 1,
          "items": {
            "$ref": "#/definitions/hookHandler"
          }
        }
      }
    },
    "hookHandler": {
      "anyOf": [
        {
          "$ref": "#/definitions/commandHandler"
        },
        {
          "$ref": "#/definitions/skippedHandler"
        }
      ]
    },
    "commandHandler": {
      "type": "object",
      "description": "Command hook handler. Commands run with the session cwd as their working directory.",
      "required": ["type", "command"],
      "additionalProperties": true,
      "properties": {
        "type": {
          "const": "command",
          "description": "Command handlers are the only hook handler type that runs in the current Codex runtime."
        },
        "command": {
          "type": "string",
          "description": "Command to execute.",
          "minLength": 1
        },
        "commandWindows": {
          "type": "string",
          "description": "Optional Windows-only command override.",
          "minLength": 1
        },
        "timeout": {
          "type": "integer",
          "description": "Timeout in seconds. Codex uses 600 seconds when omitted.",
          "minimum": 0
        },
        "statusMessage": {
          "type": "string",
          "description": "Optional status text shown while the hook runs."
        },
        "async": {
          "type": "boolean",
          "description": "Parsed by Codex, but async command hooks are not supported yet and async handlers are skipped."
        }
      }
    },
    "skippedHandler": {
      "type": "object",
      "description": "Prompt and agent handlers are parsed by Codex but skipped in the current runtime.",
      "required": ["type"],
      "additionalProperties": true,
      "properties": {
        "type": {
          "type": "string",
          "enum": ["prompt", "agent"]
        }
      }
    }
  }
}