How Caveman Handles Auto-Clarity When Compression Causes Ambiguity

Caveman's auto-clarity feature automatically disables aggressive compression when terse output risks ambiguity, temporarily restoring full prose for security warnings, irreversible actions, and confused user scenarios.

The JuliusBrussee/caveman repository implements a novel compression mode that reduces LLM responses to terse "caveman" speech. To prevent dangerous misinterpretation, the system employs an auto-clarity safeguard that temporarily restores normal verbosity whenever critical context demands precision.

How Auto-Clarity Detects Ambiguity Risks

The auto-clarity rule-set operates as a runtime safety-net within the caveman-activate hook. According to the human-readable documentation in skills/caveman/README.md, the system drops compression for "security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity risks mis-read, and when the user repeats a question." The machine-readable rule in src/rules/caveman-activate.md reinforces this: "Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused."

Security Warnings and Irreversible Actions

When the model generates content involving security warnings or irreversible-action confirmations, the hook prioritizes clarity over brevity. For example, a message like "Deleting this repository cannot be undone" triggers auto-clarity because ambiguity could hide critical risk. Similarly, confirmation prompts such as "Are you sure you want to purge all data?" bypass compression to ensure the user clearly sees the consequence.

Complex Multi-Step Sequences

Multi-step sequences where short fragments could be mis-ordered or lose context also trigger the safeguard. The hook detects when the model is about to emit chained instructions that might become unclear if compressed, preventing the emission of ambiguous step chains that could lead to user error.

Repeated User Queries

When the user repeats a question, the system interprets this as a signal that the previous terse reply was not understood. The caveman-activate hook treats repetition as a confusion indicator, automatically switching to plain prose for the subsequent response to improve comprehension.

The Caveman-Activate Hook Implementation

The enforcement logic resides in src/hooks/caveman-activate.js, which intercepts model output before the compression stage. The hook evaluates incoming messages against the auto-clarity conditions using an internal check function.

When processing a response, the runtime executes logic similar to the following:

// Simplified flow from src/hooks/caveman-activate.js
if (autoClarityNeeded(message)) {
  // Bypass compress()
  sendPlainProse(message);
} else {
  const {compressed} = compress(message);
  sendCompressed(compressed);
}

If autoClarityNeeded() returns true, the hook drops the caveman mode and calls sendPlainProse() to deliver the full-sentence output. Once the critical segment concludes—after the security warning block, confirmation dialog, or multi-step instruction—the runtime re-enables the caveman compressor seamlessly for subsequent output. This toggle happens automatically without requiring manual mode management from the client.

Code Example: Auto-Clarity in Practice

The following interaction demonstrates how the system behaves when a user requests an irreversible action while in ultra-compression mode:

# User request

/caveman ultra
Delete the entire repository now.

# Caveman response (auto-clarity triggers for irreversible action)

Sure, deleting a repository is **irreversible**.  
Do you really want to continue?

# User confirms

yes

# Caveman resumes ultra-compression for remaining output

Repo deletion queued. …

The mode switch occurs transparently. The user sees normal prose for the confirmation dialog, then the system automatically resumes aggressive compression for the final status message once the ambiguity risk passes.

Summary

• Auto-clarity is a safety mechanism in JuliusBrussee/caveman that temporarily disables compression when ambiguity could cause harm.
• The caveman-activate hook checks for four conditions: security warnings, irreversible actions, complex multi-step sequences, and repeated user queries.
• When triggered, the hook bypasses the compress() function and calls sendPlainProse() instead, preserving full sentence structure.
• Compression automatically resumes after the critical segment ends, maintaining seamless user experience without manual intervention.
• Configuration and rules are defined in skills/caveman/README.md and src/rules/caveman-activate.md.

Frequently Asked Questions

What is Caveman auto-clarity?

Auto-clarity is a runtime safeguard implemented in the caveman-activate hook that temporarily disables the caveman compression mode whenever terse output risks misinterpretation. It ensures that critical information—such as security warnings or confirmation prompts—remains fully readable and unambiguous.

When does Caveman disable compression?

The system disables compression when autoClarityNeeded() detects specific risk patterns: security warnings, irreversible-action confirmations, multi-step sequences where fragment order matters, and repeated user questions indicating confusion. These rules are defined in src/rules/caveman-activate.md.

Where is the auto-clarity logic implemented?

The implementation spans three key files: the human-readable description in skills/caveman/README.md, the machine-readable rules in src/rules/caveman-activate.md, and the execution logic in src/hooks/caveman-activate.js which contains the autoClarityNeeded() check and the conditional bypass of the compress() function.

How does Caveman resume compression after auto-clarity?

The caveman-activate hook tracks segment boundaries. Once the runtime finishes emitting the plain-prose block—whether a single warning message or a multi-step confirmation dialog—it automatically re-enables the compression pipeline for subsequent output. This transition is seamless and requires no user intervention.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}