How Caveman Auto-Disables for Security Warnings and Irreversible Actions

TLDR: Caveman’s auto-disable feature, called Auto-Clarity, embeds behavioral rules directly in the skill description that streams to the model at session start, instructing Claude to temporarily switch to normal prose whenever it encounters security warnings or irreversible actions.

The Caveman extension for Claude Code, available in the JuliusBrussee/caveman repository, implements a safety mechanism that automatically drops the "caveman" persona when critical warnings are needed. Unlike traditional implementations that parse output with conditional logic, Caveman leverages the language model's ability to follow embedded instructions within its context window. This approach ensures that security warnings and irreversible action confirmations are always communicated in clear, unambiguous language.

How Auto-Disable Works (The Auto-Clarity Rule)

Caveman’s auto-disable functionality is not implemented through JavaScript parsing or regex matching. Instead, it operates as a behavioral rule embedded within the skill description itself, which the model treats as authoritative.

Session Activation Hook

When Claude Code initializes a session, the activation hook in src/hooks/caveman-activate.js executes immediately. This hook reads the single source-of-truth file skills/caveman/SKILL.md and streams its contents directly into the model's hidden context. According to lines 59-68 of the activation hook, the system loads the skill description and ensures it becomes part of the model's runtime instructions.

The Auto-Clarity Directive

Inside skills/caveman/SKILL.md, the Auto-Clarity section explicitly defines trigger conditions that force a temporary style switch. Lines 58-66 of the skill description instruct the model to "Drop caveman when" it encounters specific scenarios:

• Security warnings about data deletion or system modifications
• Confirmations for irreversible actions
• Multi-step sequences that could be misinterpreted
• Direct user requests for clarification

Model Compliance and Output Behavior

Claude Code treats the streamed skill text as authoritative system instructions. When generating responses, the model self-monitors for the triggers defined in the Auto-Clarity rule. Upon detecting a security warning or irreversible action, the model temporarily switches to normal prose to ensure clarity, then resumes the caveman style immediately after the critical information is conveyed.

Practical Code Examples

Example 1: Database Destruction Warning

When a user requests deletion of a database table, the model automatically disables caveman mode for the warning:

// User requests table deletion
await claude.run(`
DROP TABLE users;
`);

The model outputs a clear warning before resuming the persona:

**Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
Caveman resume. Verify backup exists first.

Example 2: Force Push Confirmation

Similarly, dangerous Git operations trigger the auto-disable:

await claude.run(`
git push --force origin main
`);

Output:

**Warning:** Force-pushing rewrites remote history and can lose commits.
Caveman resume. Consider creating a backup branch first.

Example 3: Normal Operation Resumes

After clearing the security warning, standard caveman style returns automatically:

await claude.run(`
Explain how to fix the bug.
`);

Standard caveman style returns:

Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:

Key Implementation Files

The auto-disable mechanism relies on three core components:

• src/hooks/caveman-activate.js – Session-start hook that reads SKILL.md and streams it to the model as hidden context (lines 59-68).
• skills/caveman/SKILL.md – Single source of truth containing the Auto-Clarity rule that triggers auto-disable (lines 58-66).
• src/hooks/caveman-config.js – Provides safeWriteFlag and readFlag helpers for mode persistence, essential for tracking the active state across sessions.

Summary

• Auto-Clarity is a behavioral rule embedded in skills/caveman/SKILL.md, not a separate parser.
• The src/hooks/caveman-activate.js hook streams the skill description to the model at session start (lines 59-68).
• Triggers include security warnings, irreversible actions, ambiguous multi-step sequences, and user clarification requests.
• The model temporarily switches to normal prose for warnings, then automatically resumes caveman style without external enforcement.
• Compliance relies entirely on the model following the instructions in its context window.

Frequently Asked Questions

Does Caveman use regex or parsing to detect security warnings?

No. Caveman does not parse model output with JavaScript logic or regex patterns. Instead, the auto-disable functionality relies on the language model's ability to follow the Auto-Clarity rule embedded in skills/caveman/SKILL.md. The model self-regulates based on the instructions streamed into its context window at session initialization by src/hooks/caveman-activate.js.

What happens if the model forgets to resume caveman style after a warning?

The Auto-Clarity rule in SKILL.md explicitly instructs the model to resume the caveman persona after delivering the clear warning. According to the source analysis, the instruction includes the phrase "Caveman resume" or similar markers, ensuring the model returns to the restricted syntax for subsequent outputs in the same session.

Can users manually trigger auto-disable without a security warning?

Yes. The Auto-Clarity rule specifically includes "when the user asks for clarification" as a trigger condition. If a user requests that the model explain something in normal language or asks for clarification during a caveman session, the model will temporarily drop the persona to provide a clear response, then resume the restricted style.

Where is the auto-disable logic located in the codebase?

The logic is split between two primary files: src/hooks/caveman-activate.js handles the session-start streaming of the skill description (lines 59-68), while the actual behavioral rules reside in skills/caveman/SKILL.md (lines 58-66). The src/hooks/caveman-config.js file manages persistence flags but does not contain the auto-disable logic itself.

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