# SOUL Evil Hook Documentation

## Overview

The SOUL Evil hook is a feature that replaces injected `SOUL.md` content with `SOUL_EVIL.md` during specified conditions, operating entirely in memory without modifying disk files.

## Core Functionality

When `agent:bootstrap` runs, the hook can replace the `SOUL.md` content in memory before the system prompt is assembled. If the evil variant is unavailable, the system logs a warning and maintains the standard SOUL configuration.

An important limitation: this hook does not function for sub-agent runs, as they exclude `SOUL.md` from their bootstrap files.

## Configuration

Enable the hook via command:
```bash
openclaw hooks enable soul-evil
```

Then configure using JSON with these parameters:
- `file`: alternate SOUL filename (defaults to `SOUL_EVIL.md`)
- `chance`: probability value between 0–1 for random activation
- `purge.at`: scheduled daily trigger in HH:mm format (24-hour)
- `purge.duration`: window length (examples: `30s`, `10m`, `1h`)

The purge window takes precedence over random chance when both are active.

## Key Characteristics

The hook respects the timezone setting from `agents.defaults.userTimezone`, falling back to host timezone if unspecified. It requires creating `SOUL_EVIL.md` in the agent workspace root directory alongside the standard SOUL file.