Skip to main content

Hooks Architecture Overview

Hooks Architecture Overview

Last updated: 2026-04-05 Status: All hooks migrated to Kotlin/GraalVM native binaries

Architecture

ALAI uses two GraalVM native binaries for hook enforcement:

Binary Purpose Size
alai-hooks Business logic hooks (security, quality, ZAKON enforcement) 14 MB
claude-hooks Session/subagent context + post-tool logging ~14 MB

Both are Mach-O 64-bit arm64 executables compiled from Kotlin via GraalVM native-image. Zero JVM startup cost (~2-5ms per invocation).

Hook Events

Event When Hooks
PreToolUse[Bash] Before any shell command bash, evidence-gate, pipeline-gate, deploy-gate
PreToolUse[Write/Edit] Before file writes write, tech-stack-gate, lead-guard, backend-guard, hallucination
PostToolUse[.*] After any tool claude-hooks post, context-bundle-logger
Stop Session end session-cleanup, session-ledger, stop-verify
PreCompact Before context compaction session-ledger
UserPromptSubmit Before processing user message boot-enforcer, user-message-logger, auto-verify
WorktreeCreate Git worktree creation worktree-create
SessionStart New session claude-hooks session
SubagentStart New subagent claude-hooks subagent, alai-hooks subagent

Language Breakdown (Post-Migration 2026-04-05)

Language Count Usage
Kotlin/GraalVM 15 All security + quality hooks
Shell 6 Session management, boot, logging
Python 0 Fully migrated (was 9 hooks)

Migration History

  • 2026-04-01: Initial Kotlin binary (alai-hooks) with 8 hooks
  • 2026-04-05: Migrated remaining 6 Python hooks to Kotlin:
    • deploy-gate-zakon.py to alai-hooks deploy-gate
    • backend-edit-guard.py to alai-hooks backend-guard
    • hallucination-detector.py to alai-hooks hallucination (NEW, was not wired)
    • claim-blocker.py to alai-hooks claim-blocker
    • stop_verify_claims.py to alai-hooks stop-verify
    • auto_verify_claims.py to alai-hooks auto-verify
  • 2026-04-05: Python dispatchers/, lib/, backup/ archived
  • 2026-04-05: hook-daemon.py retired (socket-based Python dispatcher)

Source Code

~/system/tools/alai-hooks/
  build.gradle.kts            # Kotlin 2.2.0 + GraalVM native-image
  src/main/kotlin/com/alai/hooks/
    Main.kt                   # Dispatch router
    JsonParser.kt             # Minimal JSON parser (no reflection)
    BashSecurityGate.kt       # NPM audit, destructive commands, exfil, SMTP
    WriteSecurityGate.kt      # Protected paths, secrets detection
    EvidenceGatekeeper.kt     # ZAKON #21: evidence before task completion
    TechStackGate.kt          # ALAI tech stack enforcement
    PipelineGate.kt           # CI/CD pipeline gate
    LeadGuard.kt              # Lead/sales data protection
    DeployGateZakon.kt        # ZAKON #2/#19: CEO approval for deploys
    BackendEditGuard.kt       # ZAKON #20/#5: orchestrator vs executor
    HallucinationDetector.kt  # Anti-hallucination (facts, ports, paths, tools)
    ClaimBlocker.kt           # ZAKON #21: evidence for claims
    StopVerifyClaims.kt       # Session-end claim verification
    AutoVerifyClaims.kt       # Pre-prompt claim verification
    SessionStartContext.kt    # Session context injection
    SubagentStartContext.kt   # Subagent context injection
    PostToolLogger.kt         # Post-tool audit logging
    RoleDetector.kt           # Agent role detection
    PermissionEnforcer.kt     # Permission enforcement
    YamlPermissionLoader.kt   # YAML config loader

Building

cd ~/system/tools/alai-hooks
gradle nativeCompile
cp build/native/nativeCompile/alai-hooks ~/.claude/hooks/alai-hooks

Requires: GraalVM CE 25+, Kotlin 2.2.0, Gradle.

No comments to display

Back to top