orchestkit-hook-contract 0.1.0

Hook event contract for OrchestKit — Pydantic models, JSON schemas, and a thin validation helper. Zero runtime deps beyond pydantic.

orchestkit-hook-contract

Pydantic v2 + JSON Schema contract for Claude Code hook events. Python sibling of the npm package @orchestkit/hook-contract. Both packages regenerate from the single source of truth at spec/hook-events.spec.yml in the repo root.

Status

• M141-3 (this package): scaffold — Pydantic models, JSON schemas, structural validator, hand-rolled codegen from spec.
• M141-6 (next): cross-language parity gate CI — diff this output against the npm side field-by-field.

Install

pip install orchestkit-hook-contract

Requires Python 3.11+ and pydantic>=2.5.

Usage

from orchestkit_hook_contract import (
    HookEvent,
    HOOK_EVENT_NAMES,
    PreToolUsePayload,
    validate_hook_event,
)

# Structural validation
result = validate_hook_event({"event": "PreToolUse"})
if result.valid:
    print("known event:", result.event)

# Typed payload access
p = PreToolUsePayload(tool_name="Bash", tool_input={"cmd": "ls"})
assert p.tool_name == "Bash"

# Pydantic envelope
e = HookEvent(event="PreToolUse", payload={"tool_name": "Bash", "tool_input": {}})

Coverage

13 of the 19 hook events have typed payload classes (PreToolUsePayload, NotificationPayload, etc.). The remaining 6 events stay envelope-only — their CC payloads aren't documented enough to lock down: SessionEnd, Setup, InstructionsLoaded, WorktreeCreate, WorktreeRemove, ConfigChange.

Develop

cd packages/hook-contract-py
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -v
python scripts/codegen-py.py --check   # drift gate
python scripts/codegen-py.py           # regenerate from spec
mypy src/
ruff check src/ tests/

Why this package exists

The hook event surface is the contract between OrchestKit's TypeScript hook fan-out and any Python receiver (yonatan-hq/platform, custom analytics consumers). When the contracts drift, fields go missing in transit and observability lies. This package + the npm sibling both regenerate from one spec, eliminating that drift class.