How Caveman Handles Security Warnings and Irreversible Actions: The Auto-Clarity Rule Explained

Caveman temporarily disables its token-compression behavior and switches to normal prose whenever a response contains a security warning or irreversible action confirmation.

The Caveman project is an open-source LLM tool that applies aggressive token compression to reduce API costs, but it implements a critical safety mechanism for high-stakes communications. According to the JuliusBrussee/caveman source code, this "auto-clarity rule" ensures that security warnings and irreversible action confirmations remain unambiguous and exact, preventing the loss of crucial wording through compression.

The Auto-Clarity Rule: Defining Security-Safe Behavior

At the core of Caveman's safety mechanism is a declarative rule that specifies exactly when to suspend compression.

Rule Definition in caveman-activate.md

The rule lives in src/rules/caveman-activate.md and explicitly mandates dropping the terse caveman format for sensitive content:

Auto-Clarity: drop caveman for security warnings, irreversible actions,
user confused. Resume after.

This definition appears at line 13 of the activation rule file, establishing the protocol that the system must follow when encountering security-critical communications.

Implementation in the Activation Hook

The runtime enforcement of the auto-clarity rule occurs in the activation hook, which inspects LLM output before applying compression.

Runtime Detection Logic in caveman-activate.js

The hook src/hooks/caveman-activate.js contains the logic that scans for security-relevant patterns. At line 137, the implementation checks output content and conditionally bypasses the compression pipeline:

if (output.includes('security warning') ||
    output.includes('irreversible action')) {
  // Drop caveman for this fragment
  return normalProse(output);
}
// otherwise continue with caveman compression

When the hook detects a match, it drops caveman for that specific fragment—returning normal prose—then automatically resumes the compressed format for subsequent content. This surgical approach preserves token savings for safe content while ensuring critical warnings remain fully legible.

User-Facing Documentation

The auto-clarity behavior is documented in multiple locations to ensure both end-users and maintainers understand the safety guarantee.

README and Maintainer Guide References

Skills documentation (skills/caveman/README.md, line 20) explains the behavior to users: the skill "drops to normal prose for security warnings, irreversible-action confirmations, multi-step sequences where fragment ambiguity risks misread, and when the user repeats a question. Resumes after."

The maintainer guide (CLAUDE.md, line 223) reiterates this rule for LLM-side loading, ensuring that any system running the Caveman skill understands when to suspend compression. Additionally, src/tools/caveman-init.js contains a summary comment of this rule at line 30, providing inline documentation for developers initializing the tool.

Why Auto-Clarity Matters for Security

Security warnings often require exact wording to prevent catastrophic misinterpretation. When a user requests a dangerous operation like rm -rf /, the response must unambiguously state: "This command will permanently delete all files on the target system. Do NOT run it on production."

By temporarily disabling compression for these fragments, Caveman eliminates the risk of losing negations ("not") or modifiers ("permanently") that aggressive token reduction might otherwise strip away. The system maintains this safety boundary while preserving the efficiency benefits of compression for the remainder of the conversation.

Summary

• Caveman implements an auto-clarity rule that disables token compression for security warnings and irreversible actions.
• The rule is defined in src/rules/caveman-activate.md (line 13) and enforced by src/hooks/caveman-activate.js (line 137).
• When the hook detects "security warning" or "irreversible action" in output, it returns normal prose for that fragment only, then resumes compression.
• This behavior is documented in skills/caveman/README.md (line 20), CLAUDE.md (line 223), and src/tools/caveman-init.js (line 30).
• The mechanism ensures critical safety communications remain exact and unambiguous while maintaining token efficiency for standard dialogue.

Frequently Asked Questions

What triggers Caveman to disable its compression?

Caveman disables compression when output contains security warnings, irreversible action confirmations, indicators of user confusion, or repeated questions. The hook in src/hooks/caveman-activate.js scans for specific string patterns like "security warning" and "irreversible action" to trigger the switch to normal prose.

Does Caveman resume compression after the warning?

Yes, Caveman automatically resumes compression after the security-critical fragment has been delivered. The auto-clarity rule specifies "Resume after," meaning only the immediate warning or confirmation is rendered in full prose, while surrounding content maintains the terse caveman format.

Where is the auto-clarity rule documented?

The rule appears in multiple locations: the primary definition is in src/rules/caveman-activate.md (line 13), user-facing documentation is in skills/caveman/README.md (line 20), and maintainer guidance is in CLAUDE.md (line 223). Developer tools also reference this rule in src/tools/caveman-init.js (line 30).

Why not compress security warnings to save tokens?

Security warnings and irreversible action confirmations must remain unambiguous to prevent user error. Aggressive compression risks removing critical modifiers like "not" or "permanently," which could transform a life-saving warning into a dangerous instruction. The auto-clarity rule prioritizes safety over token savings for these high-stakes communications.

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