Metadata-Version: 2.4
Name: orchestkit-hook-contract
Version: 0.1.0
Summary: Hook event contract for OrchestKit — Pydantic models, JSON schemas, and a thin validation helper. Zero runtime deps beyond pydantic.
Project-URL: Homepage, https://github.com/yonatangross/orchestkit
Project-URL: Repository, https://github.com/yonatangross/orchestkit
Project-URL: Issues, https://github.com/yonatangross/orchestkit/issues
Project-URL: Source spec, https://github.com/yonatangross/orchestkit/blob/main/spec/hook-events.spec.yml
Author: Yonatan Gross
License-Expression: MIT
Keywords: claude-code,contract,hooks,orchestkit,schema
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: pydantic<3,>=2.5
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: pyyaml>=6.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
Description-Content-Type: text/markdown

# orchestkit-hook-contract

Pydantic v2 + JSON Schema contract for Claude Code hook events. Python sibling of the npm package [`@orchestkit/hook-contract`](../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

```bash
pip install orchestkit-hook-contract
```

Requires Python 3.11+ and `pydantic>=2.5`.

## Usage

```python
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

```bash
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.
