claude-dev-env 1.57.1 → 1.58.0

package/bin/install.mjs

@@ -165,12 +165,31 @@ const INSTALL_GROUPS = {
     ...discoverDependencyGroups(),
 };
 
-function detectPython() {
-    const candidates = [
+/**
+ * Returns the ordered python interpreter candidates to probe for the given
+ * platform. On win32 the `py -3` launcher is probed first because it resolves
+ * through the Windows registry and is immune to the Microsoft Store
+ * `python.exe` App Execution Alias that otherwise gets baked into settings.json.
+ *
+ * @param {string} platform A value from `process.platform` (e.g. 'win32', 'linux').
+ * @returns {{command: string, versionFlag: string}[]} Candidates in probe order.
+ */
+export function pythonCandidatesForPlatform(platform) {
+    const windowsOrder = [
+        { command: 'py -3', versionFlag: '--version' },
+        { command: 'python3', versionFlag: '--version' },
+        { command: 'python', versionFlag: '--version' },
+    ];
+    const defaultOrder = [
         { command: 'python3', versionFlag: '--version' },
         { command: 'python', versionFlag: '--version' },
         { command: 'py -3', versionFlag: '--version' },
     ];
+    return platform === 'win32' ? windowsOrder : defaultOrder;
+}
+
+function detectPython() {
+    const candidates = pythonCandidatesForPlatform(process.platform);
     for (const { command, versionFlag } of candidates) {
         try {
             const version = execSync(`${command} ${versionFlag}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
@@ -235,22 +254,155 @@ function backupClaudeHubBeforeOverwrite(destPath, incomingPath) {
     return backupPath;
 }
 
-function mergeHooks(hooksSourceRoot, pythonCommand) {
-    const hooksJsonPath = join(hooksSourceRoot, 'hooks', 'hooks.json');
-    if (!existsSync(hooksJsonPath)) return 0;
-    const hooksConfig = JSON.parse(readFileSync(hooksJsonPath, 'utf8'));
-    const settingsPath = join(CLAUDE_HOME, 'settings.json');
-    let settings = {};
-    if (existsSync(settingsPath)) {
-        const raw = readFileSync(settingsPath, 'utf8').trim();
-        if (raw) {
-            try { settings = JSON.parse(raw); }
-            catch { console.error('  ERROR: settings.json is malformed JSON. Fix it and rerun.'); process.exit(1); }
+/**
+ * Builds the set of hook script paths this installer manages, each relative to
+ * the hooks directory (e.g. 'blocking/code_rules_enforcer.py'), parsed from the
+ * `${CLAUDE_PLUGIN_ROOT}/hooks/<path>` references in hooks.json. Inline
+ * `python3 -c` commands reference the hooks directory without a script tail and
+ * contribute nothing.
+ *
+ * @param {{hooks: object}} hooksConfig Parsed hooks.json.
+ * @returns {Set<string>} Forward-slash relative script paths under hooks/.
+ */
+export function managedHookScriptRelativePaths(hooksConfig) {
+    const relativePaths = new Set();
+    const scriptReferencePattern = /\$\{CLAUDE_PLUGIN_ROOT\}\/hooks\/(\S+?\.py)/g;
+    for (const matcherGroups of Object.values(hooksConfig.hooks)) {
+        for (const sourceGroup of matcherGroups) {
+            for (const hook of sourceGroup.hooks) {
+                for (const scriptMatch of hook.command.matchAll(scriptReferencePattern)) {
+                    relativePaths.add(scriptMatch[1]);
+                }
+            }
+        }
+    }
+    return relativePaths;
+}
+
+/**
+ * Builds the union of managed hook script paths across the given package source
+ * roots by parsing each root's hooks/hooks.json. The installer copies hook
+ * scripts into ~/.claude/hooks/ but never copies hooks.json itself, so the
+ * uninstall and update-refresh purge must read the managed-hook set from the
+ * package source the same way the merge does, never from ~/.claude/hooks/.
+ * Roots without a hooks.json contribute nothing.
+ *
+ * @param {string[]} sourceRoots Package roots that hold a hooks/hooks.json.
+ * @returns {Set<string>} Forward-slash relative script paths under hooks/.
+ */
+export function managedHookScriptRelativePathsFromSourceRoots(sourceRoots) {
+    const relativePaths = new Set();
+    for (const sourceRoot of sourceRoots) {
+        const hooksJsonPath = join(sourceRoot, 'hooks', 'hooks.json');
+        if (!existsSync(hooksJsonPath)) continue;
+        const hooksConfig = JSON.parse(readFileSync(hooksJsonPath, 'utf8'));
+        for (const relativePath of managedHookScriptRelativePaths(hooksConfig)) {
+            relativePaths.add(relativePath);
+        }
+    }
+    return relativePaths;
+}
+
+/**
+ * Resolves every package source root the installer can copy hooks from: this
+ * package plus each resolvable dependency package that ships hooks. The purge
+ * reads hooks.json from these roots so it prunes managed entries no matter which
+ * package contributed them.
+ *
+ * @returns {string[]} Distinct package roots, this package first.
+ */
+function managedPackageSourceRoots() {
+    const dependencyRoots = Object.values(INSTALL_GROUPS)
+        .filter(group => group.packageRoot)
+        .map(group => group.packageRoot);
+    return [...new Set([PACKAGE_ROOT, ...dependencyRoots])];
+}
+
+/**
+ * Reports whether a settings.json hook command points at one of this installer's
+ * managed scripts, no matter how the home directory was written ($HOME, ~,
+ * ${HOME}, or an absolute path) or which path separator was used. Matching on
+ * the `/.claude/hooks/<relative>` tail lets a reinstall prune stale entries from
+ * earlier installs that used a different interpreter prefix, while leaving
+ * user-authored hooks outside the managed set untouched.
+ *
+ * @param {string} commandString The hook command from settings.json.
+ * @param {Set<string>} managedHookRelativePaths Managed script paths under hooks/.
+ * @returns {boolean} True when the command references a managed script.
+ */
+export function commandReferencesManagedHook(commandString, managedHookRelativePaths) {
+    const normalizedCommand = commandString.replace(/\\/g, '/');
+    if (commandIsInlineManagedValidatorRunner(normalizedCommand)) {
+        return true;
+    }
+    for (const relativePath of managedHookRelativePaths) {
+        if (commandTailEndsAtManagedHook(normalizedCommand, relativePath)) {
+            return true;
         }
     }
+    return false;
+}
+
+/**
+ * Reports whether a command contains the `/.claude/hooks/<relative>` tail ending
+ * at a path boundary: end of string, or an argument separator (whitespace, quote,
+ * or semicolon). Anchoring the tail keeps a user hook whose path is the managed
+ * tail plus a suffix (`code_rules_enforcer.py.bak`, `a.py/extra/thing.py`) outside
+ * the managed set, so it is never pruned.
+ *
+ * @param {string} normalizedCommand Forward-slash-normalized hook command.
+ * @param {string} relativePath Managed script path under hooks/.
+ * @returns {boolean} True when the managed tail ends at a path boundary.
+ */
+function commandTailEndsAtManagedHook(normalizedCommand, relativePath) {
+    const commandArgumentBoundary = /[\s'";]/;
+    const managedTail = `/.claude/hooks/${relativePath}`;
+    let searchStart = normalizedCommand.indexOf(managedTail);
+    while (searchStart !== -1) {
+        const characterAfterTail = normalizedCommand[searchStart + managedTail.length];
+        if (characterAfterTail === undefined || commandArgumentBoundary.test(characterAfterTail)) {
+            return true;
+        }
+        searchStart = normalizedCommand.indexOf(managedTail, searchStart + 1);
+    }
+    return false;
+}
+
+/**
+ * Reports whether a settings.json hook command is the inline validators-runner
+ * the installer writes in place of a standalone script. That hook inserts the
+ * managed hooks directory onto sys.path and imports run_all_validators, so it
+ * carries no `<script>.py` tail for managedHookScriptRelativePaths to record.
+ * Matching its shape lets a reinstall prune the prior copy before appending the
+ * freshly rewritten one, keeping the merge idempotent.
+ *
+ * @param {string} normalizedCommand Forward-slash-normalized hook command.
+ * @returns {boolean} True when the command is the inline validators runner.
+ */
+export function commandIsInlineManagedValidatorRunner(normalizedCommand) {
+    const inlineValidatorRunnerMarker = /sys\.path\.insert\([^)]*\.claude\/hooks[^)]*\)[\s\S]*run_all_validators/;
+    return (
+        normalizedCommand.includes('/.claude/hooks') &&
+        inlineValidatorRunnerMarker.test(normalizedCommand)
+    );
+}
+
+/**
+ * Merges the installer's managed hook groups into a settings object in memory,
+ * pruning every prior managed hook (standalone script or inline validators
+ * runner) from each matcher group before appending the freshly rewritten copies
+ * so repeated merges stay idempotent. User-authored hooks in the same group are
+ * preserved untouched.
+ *
+ * @param {object} settings The parsed settings.json object (mutated in place).
+ * @param {{hooks: object}} hooksConfig Parsed hooks.json.
+ * @param {string} pluginRootDir Directory ${CLAUDE_PLUGIN_ROOT} resolves to.
+ * @param {string} pythonCommand Interpreter command that replaces python3.
+ * @returns {number} Count of matcher groups merged.
+ */
+export function mergeHooksIntoSettings(settings, hooksConfig, pluginRootDir, pythonCommand) {
+    const managedHookRelativePaths = managedHookScriptRelativePaths(hooksConfig);
     if (!settings.hooks) settings.hooks = {};
-    const installedHooksDir = join(CLAUDE_HOME, 'hooks');
-    const pluginRootDir = CLAUDE_HOME;
     let groupCount = 0;
     for (const [eventType, matcherGroups] of Object.entries(hooksConfig.hooks)) {
         if (!settings.hooks[eventType]) settings.hooks[eventType] = [];
@@ -267,7 +419,7 @@ function mergeHooks(hooksSourceRoot, pythonCommand) {
             if (existingIndex >= 0) {
                 const existing = settings.hooks[eventType][existingIndex];
                 const userHooks = existing.hooks.filter(
-                    hook => !hook.command.includes(installedHooksDir.replace(/\\/g, '/'))
+                    hook => !commandReferencesManagedHook(hook.command, managedHookRelativePaths)
                 );
                 settings.hooks[eventType][existingIndex] = {
                     ...existing,
@@ -279,6 +431,51 @@ function mergeHooks(hooksSourceRoot, pythonCommand) {
             groupCount++;
         }
     }
+    return groupCount;
+}
+
+/**
+ * Removes every managed hook (standalone script or inline validators runner)
+ * from a settings object in memory, matching each command through
+ * commandReferencesManagedHook so entries written with any home-path style
+ * ($HOME, ~, ${HOME}, or absolute) and any path separator are pruned. Matcher
+ * groups left empty are dropped, and an empty hooks map is removed entirely.
+ * User-authored hooks outside the managed set are preserved untouched.
+ *
+ * @param {object} settings The parsed settings.json object (mutated in place).
+ * @param {Set<string>} managedHookRelativePaths Managed script paths under hooks/.
+ * @returns {void}
+ */
+export function pruneManagedHooksFromSettings(settings, managedHookRelativePaths) {
+    if (!settings.hooks) return;
+    for (const [eventType, matcherGroups] of Object.entries(settings.hooks)) {
+        settings.hooks[eventType] = matcherGroups
+            .map(group => ({
+                ...group,
+                hooks: group.hooks.filter(
+                    hook => !commandReferencesManagedHook(hook.command, managedHookRelativePaths)
+                ),
+            }))
+            .filter(group => group.hooks.length > 0);
+        if (settings.hooks[eventType].length === 0) delete settings.hooks[eventType];
+    }
+    if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+}
+
+function mergeHooks(hooksSourceRoot, pythonCommand) {
+    const hooksJsonPath = join(hooksSourceRoot, 'hooks', 'hooks.json');
+    if (!existsSync(hooksJsonPath)) return 0;
+    const hooksConfig = JSON.parse(readFileSync(hooksJsonPath, 'utf8'));
+    const settingsPath = join(CLAUDE_HOME, 'settings.json');
+    let settings = {};
+    if (existsSync(settingsPath)) {
+        const raw = readFileSync(settingsPath, 'utf8').trim();
+        if (raw) {
+            try { settings = JSON.parse(raw); }
+            catch { console.error('  ERROR: settings.json is malformed JSON. Fix it and rerun.'); process.exit(1); }
+        }
+    }
+    const groupCount = mergeHooksIntoSettings(settings, hooksConfig, CLAUDE_HOME, pythonCommand);
     writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
     return groupCount;
 }
@@ -564,17 +761,10 @@ function purgeManagedInstallation({ requireManifest }) {
     if (existsSync(settingsPath)) {
         const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
         if (settings.hooks) {
-            const installedHooksDir = join(CLAUDE_HOME, 'hooks').replace(/\\/g, '/');
-            for (const [eventType, matcherGroups] of Object.entries(settings.hooks)) {
-                settings.hooks[eventType] = matcherGroups
-                    .map(group => ({
-                        ...group,
-                        hooks: group.hooks.filter(hook => !hook.command.includes(installedHooksDir)),
-                    }))
-                    .filter(group => group.hooks.length > 0);
-                if (settings.hooks[eventType].length === 0) delete settings.hooks[eventType];
-            }
-            if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+            const managedHookRelativePaths = managedHookScriptRelativePathsFromSourceRoots(
+                managedPackageSourceRoots()
+            );
+            pruneManagedHooksFromSettings(settings, managedHookRelativePaths);
             writeFileSync(settingsPath, JSON.stringify(settings, null, 4) + '\n');
             console.log('  Hook entries removed from settings.json');
         }

package/bin/install.test.mjs

@@ -5,7 +5,16 @@ import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 
-import { collectPackageSourceConflicts, CONTENT_DIRECTORIES } from './install.mjs';
+import {
+    collectPackageSourceConflicts,
+    CONTENT_DIRECTORIES,
+    pythonCandidatesForPlatform,
+    managedHookScriptRelativePaths,
+    managedHookScriptRelativePathsFromSourceRoots,
+    commandReferencesManagedHook,
+    mergeHooksIntoSettings,
+    pruneManagedHooksFromSettings,
+} from './install.mjs';
 
 
 function createTemporaryGitRepository() {
@@ -172,3 +181,337 @@ test('collectPackageSourceConflicts surfaces both-added and deleted-by-them entr
         rmSync(repositoryRoot, { recursive: true, force: true });
     }
 });
+
+
+test('pythonCandidatesForPlatform prefers py -3 ahead of python on win32 so the Microsoft Store stub is never probed first', () => {
+    const commands = pythonCandidatesForPlatform('win32').map(candidate => candidate.command);
+    assert.equal(commands[0], 'py -3');
+    assert.ok(commands.indexOf('py -3') < commands.indexOf('python'));
+});
+
+
+test('pythonCandidatesForPlatform keeps python3 first on non-Windows platforms', () => {
+    const commands = pythonCandidatesForPlatform('linux').map(candidate => candidate.command);
+    assert.equal(commands[0], 'python3');
+});
+
+
+test('pythonCandidatesForPlatform still offers python as a win32 fallback when py -3 and python3 are absent', () => {
+    const commands = pythonCandidatesForPlatform('win32').map(candidate => candidate.command);
+    assert.ok(commands.includes('python'));
+});
+
+
+const SAMPLE_HOOKS_CONFIG = {
+    hooks: {
+        Stop: [
+            {
+                matcher: '',
+                hooks: [
+                    { command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/notification/attention_needed_notify.py', timeout: 15 },
+                    { command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/hedging_language_blocker.py', timeout: 10 },
+                ],
+            },
+        ],
+        PreToolUse: [
+            {
+                matcher: 'Write',
+                hooks: [
+                    { command: 'python3 -c "import sys; sys.path.insert(0, r\'${CLAUDE_PLUGIN_ROOT}/hooks\'); print(1)"', timeout: 5 },
+                ],
+            },
+        ],
+    },
+};
+
+
+test('managedHookScriptRelativePaths collects every installed hook script path and ignores inline -c commands', () => {
+    const relativePaths = managedHookScriptRelativePaths(SAMPLE_HOOKS_CONFIG);
+    assert.ok(relativePaths.has('notification/attention_needed_notify.py'));
+    assert.ok(relativePaths.has('blocking/hedging_language_blocker.py'));
+    assert.equal([...relativePaths].length, 2);
+});
+
+
+test('commandReferencesManagedHook matches managed scripts written with $HOME, ~, ${HOME}, and absolute path styles', () => {
+    const managedPaths = new Set(['notification/attention_needed_notify.py']);
+    assert.ok(commandReferencesManagedHook('python $HOME/.claude/hooks/notification/attention_needed_notify.py', managedPaths));
+    assert.ok(commandReferencesManagedHook('python ~/.claude/hooks/notification/attention_needed_notify.py', managedPaths));
+    assert.ok(commandReferencesManagedHook('python ${HOME}/.claude/hooks/notification/attention_needed_notify.py', managedPaths));
+    assert.ok(commandReferencesManagedHook('py -3 C:/Users/jonlo/.claude/hooks/notification/attention_needed_notify.py', managedPaths));
+    assert.ok(commandReferencesManagedHook('python /Users/jon/.claude/hooks/notification/attention_needed_notify.py', managedPaths));
+});
+
+
+test('commandReferencesManagedHook matches Windows backslash paths', () => {
+    const managedPaths = new Set(['blocking/hedging_language_blocker.py']);
+    assert.ok(commandReferencesManagedHook('py -3 C:\\Users\\jonlo\\.claude\\hooks\\blocking\\hedging_language_blocker.py', managedPaths));
+});
+
+
+test('commandReferencesManagedHook leaves user hooks outside the managed set untouched', () => {
+    const managedPaths = new Set(['notification/attention_needed_notify.py']);
+    assert.equal(commandReferencesManagedHook('python /home/me/custom-tools/my_own_hook.py', managedPaths), false);
+    assert.equal(commandReferencesManagedHook('py -3 ~/.claude/hooks/blocking/some_unmanaged_user_hook.py', managedPaths), false);
+});
+
+
+test('commandReferencesManagedHook leaves a user hook whose path is a managed tail plus a suffix untouched', () => {
+    const managedPaths = new Set(['blocking/code_rules_enforcer.py']);
+    assert.equal(commandReferencesManagedHook('python ~/.claude/hooks/blocking/code_rules_enforcer.py.bak', managedPaths), false);
+    assert.equal(commandReferencesManagedHook('python ~/.claude/hooks/blocking/code_rules_enforcer.py2', managedPaths), false);
+});
+
+
+test('commandReferencesManagedHook leaves a command whose managed tail is mid-path untouched', () => {
+    const managedPaths = new Set(['blocking/a.py']);
+    assert.equal(commandReferencesManagedHook('python /x/.claude/hooks/blocking/a.py/extra/thing.py', managedPaths), false);
+});
+
+
+test('commandReferencesManagedHook matches a managed script followed by a whitespace-separated argument', () => {
+    const managedPaths = new Set(['blocking/code_rules_enforcer.py']);
+    assert.ok(commandReferencesManagedHook('python ~/.claude/hooks/blocking/code_rules_enforcer.py PreToolUse', managedPaths));
+});
+
+
+test('commandReferencesManagedHook matches the rewritten inline validators-runner hook that carries no script tail', () => {
+    const managedPaths = new Set(['blocking/code_rules_enforcer.py']);
+    const rewrittenInlineCommand =
+        "py -3 -c \"import sys; sys.path.insert(0, r'C:/Users/jonlo/.claude/hooks'); from validators.run_all_validators import main; sys.exit(main())\"";
+    assert.ok(commandReferencesManagedHook(rewrittenInlineCommand, managedPaths));
+});
+
+
+test('commandReferencesManagedHook leaves an unmanaged inline -c command that imports a different module untouched', () => {
+    const managedPaths = new Set(['blocking/code_rules_enforcer.py']);
+    const userInlineCommand =
+        "python -c \"import sys; sys.path.insert(0, r'/home/me/tools'); from my_tools.runner import main; sys.exit(main())\"";
+    assert.equal(commandReferencesManagedHook(userInlineCommand, managedPaths), false);
+});
+
+
+function countManagedRunAllValidatorsHooks(settings) {
+    const writeEditGroups = (settings.hooks.PreToolUse || []).filter(
+        group => group.matcher === 'Write|Edit'
+    );
+    let runAllValidatorsCount = 0;
+    for (const group of writeEditGroups) {
+        for (const hook of group.hooks) {
+            if (hook.command.includes('run_all_validators')) {
+                runAllValidatorsCount++;
+            }
+        }
+    }
+    return runAllValidatorsCount;
+}
+
+
+test('mergeHooksIntoSettings is idempotent for the inline -c validators hook across two installs', () => {
+    const hooksConfig = {
+        hooks: {
+            'PreToolUse': [
+                {
+                    matcher: 'Write|Edit',
+                    hooks: [
+                        { command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py', timeout: 30 },
+                        {
+                            command:
+                                'python3 -c "import sys; sys.path.insert(0, r\'${CLAUDE_PLUGIN_ROOT}/hooks\'); from validators.run_all_validators import main; sys.exit(main())"',
+                            timeout: 15,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+    const settings = {};
+    const pluginRootDir = 'C:/Users/jonlo/.claude';
+
+    mergeHooksIntoSettings(settings, hooksConfig, pluginRootDir, 'py -3');
+    mergeHooksIntoSettings(settings, hooksConfig, pluginRootDir, 'py -3');
+
+    assert.equal(countManagedRunAllValidatorsHooks(settings), 1);
+    const writeEditGroup = settings.hooks.PreToolUse.find(group => group.matcher === 'Write|Edit');
+    assert.equal(writeEditGroup.hooks.length, 2);
+});
+
+
+test('mergeHooksIntoSettings preserves user hooks in a managed matcher group across re-merges', () => {
+    const hooksConfig = {
+        hooks: {
+            'PreToolUse': [
+                {
+                    matcher: 'Write|Edit',
+                    hooks: [
+                        {
+                            command:
+                                'python3 -c "import sys; sys.path.insert(0, r\'${CLAUDE_PLUGIN_ROOT}/hooks\'); from validators.run_all_validators import main; sys.exit(main())"',
+                            timeout: 15,
+                        },
+                    ],
+                },
+            ],
+        },
+    };
+    const userHookCommand = 'python /home/me/custom-tools/my_own_hook.py';
+    const settings = {
+        hooks: {
+            PreToolUse: [
+                { matcher: 'Write|Edit', hooks: [{ command: userHookCommand, timeout: 5 }] },
+            ],
+        },
+    };
+
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/jonlo/.claude', 'py -3');
+    mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/jonlo/.claude', 'py -3');
+
+    const writeEditGroup = settings.hooks.PreToolUse.find(group => group.matcher === 'Write|Edit');
+    const userHookSurvivors = writeEditGroup.hooks.filter(hook => hook.command === userHookCommand);
+    assert.equal(userHookSurvivors.length, 1);
+    assert.equal(countManagedRunAllValidatorsHooks(settings), 1);
+});
+
+test('pruneManagedHooksFromSettings removes a managed hook command written with the ~ home-path style', () => {
+    const managedPaths = new Set(['blocking/code_rules_enforcer.py']);
+    const settings = {
+        hooks: {
+            PreToolUse: [
+                {
+                    matcher: 'Write|Edit',
+                    hooks: [
+                        { command: 'python ~/.claude/hooks/blocking/code_rules_enforcer.py', timeout: 30 },
+                    ],
+                },
+            ],
+        },
+    };
+
+    pruneManagedHooksFromSettings(settings, managedPaths);
+
+    assert.equal(settings.hooks, undefined);
+});
+
+
+test('pruneManagedHooksFromSettings removes managed hooks in every home-path and separator style while keeping user hooks', () => {
+    const managedPaths = new Set(['notification/attention_needed_notify.py']);
+    const userHookCommand = 'python /home/me/custom-tools/my_own_hook.py';
+    const settings = {
+        hooks: {
+            Stop: [
+                {
+                    matcher: '',
+                    hooks: [
+                        { command: 'python $HOME/.claude/hooks/notification/attention_needed_notify.py', timeout: 15 },
+                        { command: 'python ${HOME}/.claude/hooks/notification/attention_needed_notify.py', timeout: 15 },
+                        { command: 'py -3 C:\\Users\\jonlo\\.claude\\hooks\\notification\\attention_needed_notify.py', timeout: 15 },
+                        { command: userHookCommand, timeout: 5 },
+                    ],
+                },
+            ],
+        },
+    };
+
+    pruneManagedHooksFromSettings(settings, managedPaths);
+
+    const stopGroup = settings.hooks.Stop.find(group => group.matcher === '');
+    assert.equal(stopGroup.hooks.length, 1);
+    assert.equal(stopGroup.hooks[0].command, userHookCommand);
+});
+
+function writeHooksJsonAtRoot(sourceRoot, hooksConfig) {
+    mkdirSync(join(sourceRoot, 'hooks'), { recursive: true });
+    writeFileSync(join(sourceRoot, 'hooks', 'hooks.json'), JSON.stringify(hooksConfig));
+}
+
+
+test('managedHookScriptRelativePathsFromSourceRoots reads each root hooks.json so purge matches every installed script', () => {
+    const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-purge-set-'));
+    try {
+        writeHooksJsonAtRoot(sourceRoot, SAMPLE_HOOKS_CONFIG);
+
+        const relativePaths = managedHookScriptRelativePathsFromSourceRoots([sourceRoot]);
+
+        assert.ok(relativePaths.has('notification/attention_needed_notify.py'));
+        assert.ok(relativePaths.has('blocking/hedging_language_blocker.py'));
+        assert.equal([...relativePaths].length, 2);
+    } finally {
+        rmSync(sourceRoot, { recursive: true, force: true });
+    }
+});
+
+
+test('managedHookScriptRelativePathsFromSourceRoots unions managed scripts across multiple package roots', () => {
+    const builtinRoot = mkdtempSync(join(tmpdir(), 'cdev-purge-builtin-'));
+    const dependencyRoot = mkdtempSync(join(tmpdir(), 'cdev-purge-dependency-'));
+    try {
+        writeHooksJsonAtRoot(builtinRoot, {
+            hooks: { Stop: [{ matcher: '', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py' }] }] },
+        });
+        writeHooksJsonAtRoot(dependencyRoot, {
+            hooks: { PreToolUse: [{ matcher: 'Bash', hooks: [{ command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/pwsh_enforcer.py' }] }] },
+        });
+
+        const relativePaths = managedHookScriptRelativePathsFromSourceRoots([builtinRoot, dependencyRoot]);
+
+        assert.ok(relativePaths.has('blocking/code_rules_enforcer.py'));
+        assert.ok(relativePaths.has('blocking/pwsh_enforcer.py'));
+        assert.equal([...relativePaths].length, 2);
+    } finally {
+        rmSync(builtinRoot, { recursive: true, force: true });
+        rmSync(dependencyRoot, { recursive: true, force: true });
+    }
+});
+
+
+test('managedHookScriptRelativePathsFromSourceRoots skips roots whose hooks.json is absent', () => {
+    const rootWithoutHooks = mkdtempSync(join(tmpdir(), 'cdev-purge-empty-'));
+    try {
+        const relativePaths = managedHookScriptRelativePathsFromSourceRoots([rootWithoutHooks]);
+        assert.equal([...relativePaths].length, 0);
+    } finally {
+        rmSync(rootWithoutHooks, { recursive: true, force: true });
+    }
+});
+
+
+test('purge set sourced from package hooks.json prunes standalone managed script hooks and keeps user hooks', () => {
+    const sourceRoot = mkdtempSync(join(tmpdir(), 'cdev-purge-prune-'));
+    try {
+        writeHooksJsonAtRoot(sourceRoot, {
+            hooks: {
+                PreToolUse: [
+                    {
+                        matcher: 'Write|Edit',
+                        hooks: [
+                            { command: 'python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/code_rules_enforcer.py', timeout: 30 },
+                        ],
+                    },
+                ],
+            },
+        });
+        const userHookCommand = 'python /home/me/custom-tools/my_own_hook.py';
+        const settings = {
+            hooks: {
+                PreToolUse: [
+                    {
+                        matcher: 'Write|Edit',
+                        hooks: [
+                            { command: 'py -3 C:\\Users\\jonlo\\.claude\\hooks\\blocking\\code_rules_enforcer.py', timeout: 30 },
+                            { command: userHookCommand, timeout: 5 },
+                        ],
+                    },
+                ],
+            },
+        };
+
+        const managedHookRelativePaths = managedHookScriptRelativePathsFromSourceRoots([sourceRoot]);
+        pruneManagedHooksFromSettings(settings, managedHookRelativePaths);
+
+        const writeEditGroup = settings.hooks.PreToolUse.find(group => group.matcher === 'Write|Edit');
+        assert.equal(writeEditGroup.hooks.length, 1);
+        assert.equal(writeEditGroup.hooks[0].command, userHookCommand);
+    } finally {
+        rmSync(sourceRoot, { recursive: true, force: true });
+    }
+});