Z.A.E.B.A.L

Zaebal? · Audit · Errors · Break · Analyze · Leave no assumption

Read this in other languages
🇺🇸 English · 🇷🇺 Русский · 🇨🇳 简体中文

Profanity-triggered self-audit for coding agents.
Z.A.E.B.A.L. treats user frustration as an operational signal: stop, re-check the agent's assumptions, and escalate repeated failures to an independent auditor.

Capabilities · How it works · Install · Configuration · Architecture

Why it exists

When a coding agent gets stuck, it often repeats the same action with small variations because one underlying belief about the task or codebase is wrong. The agent still treats that belief as a fact, so another self-check can reproduce the same mistake.

Z.A.E.B.A.L. adds a feedback loop to the user-message boundary:

• profanity and direct complaints become an audit signal;
• positive profanity such as “fucking great” does not add to the streak and closes an active incident as an acknowledgment;
• repeated signals escalate from a local protocol to a full stop;
• at level 3, an external agent reads the transcript and repository evidence;
• work resumes only after an explicit user acknowledgment.

The current release does not install a technical tool lock. The protocol changes the agent's instructions and asks it to stop; the human always retains the final control.

Mutation-lock feasibility

Research completed on 2026-07-31 shows that a blocking mutation STOP is technically possible on all four adapters, but with different guarantees:

No lock or state machine is added yet. The text fixes and incident telemetry should first show whether a discipline-based STOP remains insufficient.

Capability map

How it works

User message
    │
    ▼
Host adapter
UserPromptSubmit / chat.message
    │
    ▼
core/zaebal.py
normalize → detect → classify
    │
    ├─ clean / praise ───────────────────────────────► silence
    │
    └─ directed (+1.0) / ambiguous (+0.5)
                         │
                         ▼
                per-session streak
                         │
              ┌──────────┼──────────┐
              ▼          ▼          ▼
             L1         L2         L3
              │          │          ├─ external auditor
              └──────────┴──────────┴─ protocol injected into context

Escalation levels

Directed complaints add 1.0; profanity without a detected addressee adds 0.5. The window is 30 minutes. Calm questions do not reset it. Genuine praise or an explicit acknowledgment does.

Install

Requirements:

• python3; the core uses only the standard library;
• at least one supported agent CLI if external auditing is enabled.

From the repository root:

chmod +x install.sh
./install.sh

The installer detects available hosts, copies the core to ~/.zaebal/, and updates only the relevant user configuration:

Installation is idempotent: existing Z.A.E.B.A.L. hook entries are replaced, while unrelated settings and ~/.zaebal/config.json are preserved. Restart active agent sessions after installation.

Verify the hook

Run the core directly without touching your normal state:

echo '{"session_id":"demo","prompt":"ты меня заебал"}' \
  | ZAEBAL_STATE_DIR="$(mktemp -d)" python3 core/zaebal.py --host kimi

The output should contain <zaebal level="1">.

Positive profanity should remain silent:

echo '{"session_id":"demo-praise","prompt":"this is fucking great"}' \
  | ZAEBAL_STATE_DIR="$(mktemp -d)" python3 core/zaebal.py --host kimi

Configuration

Defaults live in core/config.json. User overrides live in ~/.zaebal/config.json and are loaded on the next trigger:

{
  "auditor": "same",
  "audit_levels": [3],
  "auditor_timeout_sec": 90,
  "auditor_command": "",
  "transcript_tail_chars": 12000
}

Example: use Claude to audit a Codex session:

{
  "auditor": "claude"
}

Architecture

zaebal/
├── core/
│   ├── zaebal.py          # detection, state, escalation, transcript and auditor
│   ├── config.json        # default runtime configuration
│   ├── protocol/          # L1.md, L2.md, L3.md
│   └── wordlists/         # ru.txt, en.txt, zh.txt
├── adapters/
│   ├── claude-code/       # JSON hook example
│   ├── codex/             # JSON hook example
│   ├── kimi-cli/          # TOML hook block
│   └── opencode/          # chat.message plugin
├── skills/zaebal/         # agent-facing protocol and configuration reference
├── tests/                 # unit and end-to-end contract tests
├── install.sh             # idempotent host integration
└── uninstall.sh           # hook removal and config backup

The Python core is the single source of runtime behavior. Host adapters only translate their event payload into the shared JSON contract and inject non-empty stdout back into the agent context.

Runtime state is stored under ~/.zaebal/:

~/.zaebal/
├── core/          # installed copy
├── config.json    # optional user overrides
├── state.json     # per-session weighted trigger history
├── incidents.jsonl # metadata-only trigger and acknowledgment events
└── state.lock     # POSIX lock for concurrent hooks

The auditor subprocess receives ZAEBAL_INTERNAL=1, preventing the globally installed hook from reacting to profanity quoted inside its own audit prompt.

Tests

cd tests
python3 -m unittest test_zaebal -v

The suite covers normalization, RU/EN/ZH detection, meta-mention false positives, praise handling, weighted escalation, concurrent state writes, telemetry, portable installer paths, acknowledgment, anti-recursion, auditor sandbox arguments, failures, and end-to-end protocol injection.

Known limitations

• Detection is heuristic. Sarcasm and unusual context can still produce false positives or false negatives.
• The detector does not identify non-profane action loops; adding a general loop detector would be a separate product with its own false-positive model.
• State locking uses POSIX fcntl; concurrent hooks on Windows can lose updates.
• The Kimi and OpenCode auditor commands are not technically sandboxed by Z.A.E.B.A.L.; they rely on the audit prompt and any restrictions already configured in those hosts.
• External audits are synchronous on configured levels, so the user waits for the auditor or timeout.

Uninstall

./uninstall.sh

Hooks, the OpenCode plugin, installed skills, and ~/.zaebal/ are removed. If a user configuration exists, it is copied to ~/zaebal-config.backup.json first.