# 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.