gate: Python API#

The stable Python surface is deliberately small. Most users should use the CLI or Claude Code plugin; integrations that already receive hook payloads can call process() directly.

gate.process(payload: Any, config: dict[str, Any] | None = None) → dict[str, Any] | None#

Dispatch one hook payload; return the JSON decision to emit, or None for silence.

This is the pure-ish core (side effects: notifications and temp-file stamps) used by both the script entrypoint below and the test suite / selftest CLI command.

Parameters:

  • payload – One hook-event payload from the agent harness.

  • config – Resolved gate configuration. The active user configuration is loaded when omitted.

Returns:

A Claude Code deny decision for a confirmed gated launch, otherwise None.

Examples

Pass the harness payload and disable notifications in an embedding:

>>> config = {**DEFAULTS, 'notify': False}
>>> payload = {
...     'hook_event_name': 'PreToolUse',
...     'tool_name': 'Agent',
...     'session_id': 'docs-example',
...     'tool_input': {'subagent_type': 'docs-example', 'model': 'opus'},
... }
>>> decision = process(payload, config)
>>> decision['hookSpecificOutput']['permissionDecision']
'deny'
>>> payload['tool_input']['model'] = 'haiku'
>>> process(payload, config) is None
True

Unknown payloads fail open:

>>> process({'unrecognized': True}, config) is None
True

The disabled extension contract is documented under action admission. Constructing policies does not register or activate a native hook.

Deterministic extensions are importable from gate.policies. The Unicode policy’s scanner, repairer, and two policy classes are documented under Unicode write policy. The bulletin validator and content-free route seam are documented under Bulletin and Controlled Prose routing. The bounded integer and boolean regularizer is documented under Primitive Typist policy.