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

Destructive Command Guard (dcg) automatically re-registers its protective hook in Claude Code's 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. 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)
• 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, 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 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, 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 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 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:

export DCG_NO_SELF_HEAL=1
dcg hook -- incoming-command

To permanently disable via configuration file:

[general]
self_heal_hook = false

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

export DCG_SELF_HEAL_HOOK=true

Unit Test Coverage

The self-heal implementation includes comprehensive unit tests in 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
• 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 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 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 (lines 1221-3312), entry point in src/main.rs (line 560), implementation in 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 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, it prints an error message to stderr at line 11474 in 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. 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.

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