# How Self-Heal Hook Registration Restores Claude Code Settings After Overwrites

> Learn how Destructive Command Guard's self-heal hook registration automatically restores Claude Code settings after overwrites. Protect your configurations effortlessly.

- Repository: [Jeff Emanuel/destructive_command_guard](https://github.com/Dicklesworthstone/destructive_command_guard)
- Tags: internals
- Published: 2026-07-16

---

**Destructive Command Guard (dcg) automatically re-registers its protective hook in Claude Code's [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json) whenever the file is overwritten, using a configurable self-heal routine that checks and restores the hook definition before executing commands.**

The self-heal hook registration mechanism ensures that dcg remains active even after Claude Code reinstalls, updates, or manual settings resets that wipe the guard's configuration. When running in hook mode, dcg validates its presence in the IDE's configuration and silently repairs any damage to maintain continuous protection against destructive commands.

## Configuration Flag for Self-Healing

The self-heal behavior is controlled by the `self_heal_hook` boolean flag declared in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs). By default, this option is set to `true`, enabling automatic recovery without user intervention.

The configuration system reads this flag from multiple sources with the following precedence:

- **Environment variable**: `DCG_NO_SELF_HEAL` disables the feature globally when set to any value
- **Environment override**: `DCG_SELF_HEAL_HOOK` can force the flag on or off for individual runs (parsed at lines 3616-3618 in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs))
- **Config file**: The `[general]` section in `~/.config/dcg/config.toml` accepts `self_heal_hook = false` to persistently disable the feature

The default initialization and parsing logic appears at lines 1221-1227 and 1256-1258 in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs), with the final configuration resolution occurring at lines 3311-3312.

## Hook Registration Flow in the Main Loop

When dcg launches in hook mode, the entry point in [`src/main.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/main.rs) evaluates the self-heal flag before processing any incoming commands. At line 560, the application checks `cfg.general.self_heal_hook` and conditionally invokes the healing routine.

This placement ensures that dcg verifies its hook integrity *before* evaluating potentially dangerous commands. If the routine detects a missing or corrupted hook entry, it blocks command execution until the configuration is restored, preventing a window where destructive operations could bypass the guard.

## Self-Heal Implementation Details

The core logic resides in [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs), beginning at the documented comment block on line 11458. The implementation follows a strict validation and repair workflow.

### Reading and Validating settings.json

The routine first locates and parses Claude Code's [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json) file. It searches specifically for the dcg hook entry, identified by the `"dcg"` key containing the hook configuration object. The validator checks both the presence of this key and the structural integrity of its value, ensuring the binary path and execution parameters are correctly formatted.

### Rewriting the Hook Entry

If validation fails or the entry is absent, dcg generates a fresh hook definition pointing to the current binary path via `env::current_exe()`. It then atomically rewrites the [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json) file to include the restored dcg configuration while preserving all other Claude Code settings.

Error handling at line 11474 ensures that any failures during re-registration are reported to `stderr` and cause immediate termination of the command evaluation. This fail-closed design prevents execution in an unprotected state when the self-heal mechanism cannot guarantee hook integrity.

## Disabling Self-Heal When Needed

Users can disable the self-heal mechanism for debugging or manual configuration management using either environment variables or the configuration file.

To disable for a single session:

```bash
export DCG_NO_SELF_HEAL=1
dcg hook -- incoming-command

```

To permanently disable via configuration file:

```toml
[general]
self_heal_hook = false

```

To force enable for a single run (overriding config file settings):

```bash
export DCG_SELF_HEAL_HOOK=true

```

## Unit Test Coverage

The self-heal implementation includes comprehensive unit tests in [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs) (lines 17793-17866) that verify three critical scenarios:

- **`self_heal_reregisters_missing_hook`**: Confirms that dcg adds the hook entry when it is completely absent from [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json)
- **`self_heal_noop_when_hook_present`**: Validates that a correctly configured hook remains untouched, avoiding unnecessary file writes
- **`self_heal_handles_overwritten_settings`**: Ensures recovery succeeds even when the entire [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json) has been replaced with default Claude Code settings, simulating a reinstall scenario

These tests use mocked filesystem operations to safely verify the parsing and serialization logic without modifying actual user configurations.

## Summary

- **Automatic recovery**: The self-heal mechanism in dcg detects when Claude Code's [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json) has been overwritten and immediately restores the protective hook definition
- **Configurable behavior**: Control the feature via `DCG_NO_SELF_HEAL`, `DCG_SELF_HEAL_HOOK`, or the `self_heal_hook` setting in `~/.config/dcg/config.toml`
- **Fail-closed design**: If self-heal fails, dcg blocks command execution rather than running unprotected, with errors reported to `stderr`
- **Source locations**: Configuration parsing in [`src/config.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/config.rs) (lines 1221-3312), entry point in [`src/main.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/main.rs) (line 560), implementation in [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs) (line 11458), and tests at lines 17793-17866

## Frequently Asked Questions

### What triggers the self-heal mechanism?

The self-heal check runs every time dcg operates in hook mode before evaluating the incoming command. It triggers whenever the `"dcg"` entry is missing from Claude Code's [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json) or when the existing entry contains malformed JSON or incorrect binary paths. This commonly occurs after Claude Code updates, reinstalls, or when users manually reset their IDE settings to defaults.

### How do I disable self-heal if I need to modify settings.json manually?

Set the environment variable `DCG_NO_SELF_HEAL=1` before running dcg commands to disable the feature for that session. For permanent disabling, add `self_heal_hook = false` under the `[general]` section in your dcg configuration file at `~/.config/dcg/config.toml`. This prevents dcg from overwriting your manual changes while still allowing the guard to function if the hook remains correctly configured.

### What happens if the self-heal routine fails?

If the self-heal routine encounters filesystem permissions errors, JSON parsing failures, or cannot write to [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json), it prints an error message to `stderr` at line 11474 in [`src/cli.rs`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/src/cli.rs) and aborts the command execution. This fail-closed behavior ensures that dcg never evaluates destructive commands while in an unprotected state where the hook might not intercept dangerous operations.

### Does self-heal modify other Claude Code settings?

No, the self-heal implementation specifically targets only the `"dcg"` hook entry within [`settings.json`](https://github.com/Dicklesworthstone/destructive_command_guard/blob/main/settings.json). The routine preserves all other Claude Code configurations, including themes, keybindings, and other extensions. It performs a surgical update that inserts or replaces only the dcg hook definition while maintaining the integrity of the surrounding JSON structure.