claude-dev-env 4.3.0 → 7.1.0

package/bin/install.policy-lint.test.mjs

@@ -0,0 +1,130 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import {
+    FOLDED_HOOK_RELATIVE_PATHS,
+    RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS,
+    mergeHooksIntoSettings,
+} from './install.mjs';
+
+const allRetiredWriteHooks = [
+    'blocking/code_rules_enforcer.py',
+    'blocking/tdd_enforcer.py',
+    'blocking/windows_rmtree_blocker.py',
+    'blocking/state_description_blocker.py',
+    'blocking/subprocess_budget_completeness.py',
+    'blocking/hook_prose_detector_consistency.py',
+    'blocking/workflow_substitution_slot_blocker.py',
+];
+const allRetiredPolicyRegistrations = [
+    'blocking/plain_language_blocker.py',
+    'lifecycle/config_change_guard.py',
+    'blocking/docstring_rule_gate_count_blocker.py',
+    'blocking/write_existing_file_blocker.py',
+    'blocking/sensitive_file_protector.py',
+    'blocking/pii_prevention_blocker.py',
+    'blocking/duplicate_rmtree_helper_blocker.py',
+    'blocking/claude_md_orphan_file_blocker.py',
+    'blocking/package_inventory_stale_blocker.py',
+    'blocking/env_var_table_code_drift_blocker.py',
+    'blocking/pytest_testpaths_orphan_blocker.py',
+    'blocking/destructive_command_blocker.py',
+    'blocking/shell_substitution_blocker.py',
+    'blocking/piped_pytest_blocker.py',
+    'blocking/cursor_cli_python_misfire_blocker.py',
+    'blocking/unscoped_search_blocker.py',
+    'blocking/nas_ssh_binary_enforcer.py',
+    'blocking/block_main_commit.py',
+    'blocking/session_edit_stage_gate.py',
+    'blocking/bash_pre_tool_use_dispatcher.py',
+    'blocking/stop_dispatcher.py',
+    'blocking/bot_mention_comment_blocker.py',
+    'blocking/fable_spawn_gate.py',
+    'blocking/luna_fast_mode_gate.py',
+    'blocking/orchestrator_refresh_reschedule_gate.py',
+    'blocking/ask_user_question_shape_blocker.py',
+    'blocking/send_user_file_open_locally_blocker.py',
+    'blocking/question_to_user_enforcer.py',
+    'blocking/session_handoff_blocker.py',
+];
+const sourceHooks = JSON.parse(readFileSync(new URL('../hooks/hooks.json', import.meta.url), 'utf8'));
+const installedRoot = '/fixture-home/.claude';
+const foreignCommand = 'python /unmanaged/keep_this_hook.py';
+const foreignSessionCommand = 'node /unmanaged/session.js';
+
+function legacySettings() {
+    return {
+        permissions: {
+            allow: ['Read'],
+            deny: ['Bash(git push --force)'],
+            ask: ['Bash(git push)'],
+        },
+        hooks: {
+            PreToolUse: [{
+                matcher: 'Write|Edit|MultiEdit|apply_patch',
+                hooks: [
+                    { type: 'command', command: foreignCommand, timeout: 17 },
+                    ...allRetiredWriteHooks.map(relativePath => ({
+                        type: 'command',
+                        command: `python ${installedRoot}/hooks/${relativePath}`,
+                        timeout: 10,
+                    })),
+                    ...allRetiredPolicyRegistrations.map(relativePath => ({
+                        type: 'command',
+                        command: `python ${installedRoot}/hooks/${relativePath}`,
+                        timeout: 10,
+                    })),
+                ],
+            }],
+            SessionStart: [{
+                matcher: '',
+                hooks: [{ type: 'command', command: foreignSessionCommand, timeout: 9 }],
+            }],
+        },
+    };
+}
+
+function allCommands(settings) {
+    return Object.values(settings.hooks).flatMap(groups =>
+        groups.flatMap(group => group.hooks.map(hook => hook.command)));
+}
+
+test('every retired write registration already has an installer-owned prune path', () => {
+    for (const relativePath of allRetiredWriteHooks) {
+        assert.ok(FOLDED_HOOK_RELATIVE_PATHS.has(relativePath), relativePath);
+    }
+});
+
+test('every retired policy registration has an installer-owned prune path', () => {
+    for (const relativePath of allRetiredPolicyRegistrations) {
+        assert.ok(RETIRED_HOOK_REGISTRATION_RELATIVE_PATHS.has(relativePath), relativePath);
+    }
+});
+
+test('upgrade prunes legacy direct file checks while retaining foreign hooks', () => {
+    const settings = legacySettings();
+    mergeHooksIntoSettings(settings, sourceHooks, installedRoot, 'python3');
+    const commands = allCommands(settings);
+    for (const relativePath of [...allRetiredWriteHooks, ...allRetiredPolicyRegistrations]) {
+        assert.ok(!commands.some(command => command.includes(relativePath)), relativePath);
+    }
+    assert.ok(commands.includes(foreignCommand));
+    assert.ok(commands.includes(foreignSessionCommand));
+    assert.deepEqual(settings.permissions, {
+        allow: ['Read'],
+        deny: ['Bash(git push --force)'],
+        ask: ['Bash(git push)'],
+    });
+    assert.ok(commands.every(command => !command.includes('/blocking/stop_dispatcher.py')));
+    assert.ok(commands.some(command => command.includes('/blocking/pre_tool_use_dispatcher.py')));
+    assert.ok(commands.every(command => !command.includes('/blocking/bash_pre_tool_use_dispatcher.py')));
+});
+
+test('reinstall does not restore retired direct checks or duplicate foreign hooks', () => {
+    const settings = legacySettings();
+    mergeHooksIntoSettings(settings, sourceHooks, installedRoot, 'python3');
+    const firstInstall = structuredClone(settings);
+    mergeHooksIntoSettings(settings, sourceHooks, installedRoot, 'python3');
+    assert.deepEqual(settings, firstInstall);
+    assert.equal(allCommands(settings).filter(command => command === foreignCommand).length, 1);
+});

package/bin/install.profiles.test.mjs

@@ -244,6 +244,16 @@ test('install.mjs --help documents profile target selection', () => {
     assert.match(result.stdout, /targetIdentity|target identity|per target/i);
 });
 
+test('install.mjs --help states that a positional path argument carries no meaning', () => {
+    const result = spawnSync(process.execPath, [INSTALL_MODULE_PATH, '--help'], {
+        encoding: 'utf8',
+        env: process.env,
+    });
+    assert.equal(result.status, 0, result.stderr);
+    assert.match(result.stdout, /reads only flags/i);
+    assert.match(result.stdout, /path argument/i);
+});
+
 test('install.mjs wires select-install-targets for multi-profile entry', () => {
     const source = readFileSync(INSTALL_MODULE_PATH, 'utf8');
     assert.match(source, /select-install-targets\.mjs/);

package/bin/install.prune.test.mjs

@@ -13,6 +13,7 @@ import {
 import { tmpdir } from 'node:os';
 import { join, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { detectPython } from './install.mjs';
 const THIS_DIRECTORY = dirname(fileURLToPath(import.meta.url));
 const INSTALLER_PATH = join(THIS_DIRECTORY, 'install.mjs');
 const INSTALLER_PROCESS_TIMEOUT_MS = 60_000;
@@ -25,16 +26,43 @@ const RETIRED_SKILL_DIRECTORIES = [
     'post-audit-findings',
     'pr-consistency-audit',
     'bdd-protocol',
+    'hitl',
+    'autoconverge',
+    'pr-cleanup',
+    'pr-name-by-capability',
+    'pr-plain-language-cleanup',
+    'pr-refinement',
+    'pr-shared-extraction',
+    'pr-small-cl',
+    'pr-title-description',
+    'prototype',
+    'rebase',
+    'review-router',
+    'review-tier',
+    'run-claude-dev-env',
+    'session-log',
+    'session-tidy',
+    'source-command-sr-loop',
+    'update',
 ];
 const PERSONAL_SKILL_DIRECTORIES = ['credit-card-picker', 'midjourney-sref'];
-const SHIPPED_SKILL_DIRECTORY = 'autoconverge';
+const SHIPPED_SKILL_DIRECTORY = 'e-code-review';
 const PRUNED_BACKUP_DIRECTORY_NAME = '.claude-dev-env-pruned';
 const SKIP_PRUNE_NOTICE_MARKER = 'Skipping retired-skill and stale-file prune';
 const STALE_SKILL_FILE_RELATIVE_SEGMENTS = ['scripts', 'retired_module.py'];
 const RUNTIME_ARTIFACT_RELATIVE_SEGMENTS = ['scripts', '__pycache__', 'helper.cpython-312.pyc'];
 const SCOPED_GROUP_SKILL_DIRECTORY = 'orchestrator';
-const CORE_REVIEW_GUIDE_SKILL_DIRECTORIES = [
-    'pr-small-cl',
+const CORE_SKILL_DIRECTORIES = [
+    'orchestrator',
+    'orchestrator-refresh',
+    'team-advisor',
+    'grok-spawn',
+    'everything-search',
+    'test-runner',
+    'privacy-hygiene',
+    'issue-tracker',
+    'task-build',
+    'eli5',
 ];
 const PRIOR_RUN_BACKUP_DIRECTORY_NAMES = [
     '2020-01-01T00-00-00-000Z',
@@ -57,6 +85,8 @@ const STALE_RULE_FILE_NAME = 'retired-rule.md';
 const STALE_SHARED_FILE_SEGMENTS = ['pr-loop', 'retired_shared.md'];
 const STALE_SHARED_SKILL_FILE_SEGMENTS = [SHARED_DIRECTORY_NAME, 'retired_skill_shared.md'];
 const RETIRED_HOOK_RELATIVE_SEGMENTS = ['blocking', 'retired_gate.py'];
+const RETIRED_HOOK_SEEDED_CONTENTS = 'a gate an earlier revision shipped\n';
+const FOLDED_RETIRED_HOOK_RELATIVE_SEGMENTS = ['blocking', 'ask_user_question_shape_blocker.py'];
 const USER_HOOK_COMMAND = 'python3 my_own_gate.py --user-authored';
 const RETIRED_HOOK_EVENT_TYPE = 'PreToolUse';
 const DROPPED_HOOK_EVENT_TYPE = 'PreCompact';
@@ -150,7 +180,7 @@ function createSandbox(homeDirectoryPrefix = 'cdev-prune-home-') {
     return { homeDirectory, claudeDirectory, skillsDirectory, manifestPath };
 }
 
-test('a core install runs the spaced-path Write dispatcher and captures its red denial', () => {
+test('a core install runs the spaced-path Write dispatcher and allows the write', () => {
     const sandbox = createSandbox('cdev prune & (home)-');
     try {
         runInstaller(sandbox.homeDirectory, ['--only', 'core']);
@@ -177,12 +207,8 @@ test('a core install runs the spaced-path Write dispatcher and captures its red
         });
 
         assert.equal(dispatcherRun.status, 0, dispatcherRun.stderr);
-        const shownRedDecision = JSON.parse(dispatcherRun.stdout.trim());
-        assert.equal(shownRedDecision.hookSpecificOutput.permissionDecision, 'deny');
-        assert.match(
-            shownRedDecision.hookSpecificOutput.permissionDecisionReason,
-            /BLOCKED: Write on existing file/,
-        );
+        assert.equal(dispatcherRun.stdout.trim(), '', 'no hosted hook denies a Write');
+        assert.equal(readFileSync(protectedFilePath, 'utf8'), 'existing content\n');
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
     }
@@ -693,25 +719,33 @@ test('a scoped --only install leaves retired skills in place because prune runs
     }
 });
 
-test('a full reinstall keeps autoconverge because the package ships it again', () => {
+test('a full reinstall keeps the skill-builder stub and archives its obsolete support files', () => {
     const sandbox = createSandbox();
     try {
-        plantSkillDirectory(sandbox.skillsDirectory, 'autoconverge', true);
-        writeFileSync(join(sandbox.skillsDirectory, 'autoconverge', 'SKILL.md'), 'stale seeded copy\n');
+        const skillName = 'skill-builder';
+        plantSkillDirectory(sandbox.skillsDirectory, skillName, true);
+        const stubPath = join(sandbox.skillsDirectory, skillName, 'SKILL.md');
+        const obsoleteReferencePath = join(sandbox.skillsDirectory, skillName, 'references', 'retired.md');
+        writeFileWithParents(obsoleteReferencePath, 'obsolete skill-builder guidance\n');
+        writeFileSync(sandbox.manifestPath, JSON.stringify({
+            package: 'claude-dev-env',
+            version: '0.0.0',
+            installedAt: new Date().toISOString(),
+            files: [stubPath, obsoleteReferencePath],
+            skills: [skillName],
+        }, null, 2) + '\n');
 
         const installerOutput = runInstaller(sandbox.homeDirectory, []);
 
+        assert.equal(installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER), false);
+        assert.equal(existsSync(stubPath), true, 'the requested stub stays installed');
+        assert.match(readFileSync(stubPath, 'utf8'), /TODO: Rework to follow pstack philosophy\./);
+        assert.ok(readManifest(sandbox.manifestPath).skills.includes(skillName));
+        assert.equal(existsSync(obsoleteReferencePath), false);
         assert.equal(
-            installerOutput.includes(SKIP_PRUNE_NOTICE_MARKER),
-            false,
-            'the full install runs the prune rather than skipping it',
-        );
-        const restoredSkillPath = join(sandbox.skillsDirectory, 'autoconverge', 'SKILL.md');
-        assert.equal(existsSync(restoredSkillPath), true, 'autoconverge survives and is reinstalled');
-        assert.notEqual(
-            readFileSync(restoredSkillPath, 'utf8'),
-            'stale seeded copy\n',
-            'the shipped autoconverge overwrites the stale seeded copy',
+            prunedSkillBackupContains(sandbox.claudeDirectory, join(skillName, 'references', 'retired.md')),
+            true,
+            'old implementation files move to the recovery backup while the stub stays',
         );
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
@@ -739,20 +773,24 @@ test('a scoped --only install records the skill names it installed', () => {
     }
 });
 
-test('a scoped core install ships the canonical review guide skills', () => {
+test('a fresh scoped core install ships active skills and omits retired skills', () => {
     const sandbox = createSandbox();
     try {
         runInstaller(sandbox.homeDirectory, ['--only', 'core']);
 
-        const missingGuideSkillNames = CORE_REVIEW_GUIDE_SKILL_DIRECTORIES.filter(
+        const missingSkillNames = CORE_SKILL_DIRECTORIES.filter(
             eachSkillName => !existsSync(join(sandbox.skillsDirectory, eachSkillName, 'SKILL.md')),
         );
-        assert.deepEqual(missingGuideSkillNames, []);
+        assert.deepEqual(missingSkillNames, []);
 
         const recordedSkillNames = new Set(readManifest(sandbox.manifestPath).skills);
-        for (const eachSkillName of CORE_REVIEW_GUIDE_SKILL_DIRECTORIES) {
+        for (const eachSkillName of CORE_SKILL_DIRECTORIES) {
             assert.equal(recordedSkillNames.has(eachSkillName), true);
         }
+        for (const eachSkillName of RETIRED_SKILL_DIRECTORIES) {
+            assert.equal(existsSync(join(sandbox.skillsDirectory, eachSkillName)), false);
+            assert.equal(recordedSkillNames.has(eachSkillName), false);
+        }
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
     }
@@ -919,7 +957,7 @@ function seedRetiredManagedHook(sandbox) {
     const retiredHookPath = join(
         sandbox.claudeDirectory, HOOKS_DIRECTORY_NAME, ...RETIRED_HOOK_RELATIVE_SEGMENTS,
     );
-    writeFileWithParents(retiredHookPath, 'a gate an earlier revision shipped\n');
+    writeFileWithParents(retiredHookPath, RETIRED_HOOK_SEEDED_CONTENTS);
     appendManifestFiles(sandbox.manifestPath, [retiredHookPath]);
     const retiredHookCommand = `python3 "${retiredHookPath.replace(/\\/g, '/')}"`;
     const lookalikeHookCommand = `python3 "${retiredHookPath.replace(/\\/g, '/')}.bak"`;
@@ -1019,7 +1057,7 @@ test('a full reinstall leaves a manifest-recorded path under no managed root in
     }
 });
 
-test('a reinstall removes a retired post-commit shim and preserves a foreign git hook', () => {
+test('a reinstall regenerates a stale post-commit shim and preserves a foreign git hook', () => {
     const sandbox = createSandbox();
     try {
         runInstaller(sandbox.homeDirectory, []);
@@ -1029,18 +1067,18 @@ test('a reinstall removes a retired post-commit shim and preserves a foreign git
         const postCommitShimPath = join(gitHooksDirectory, POST_COMMIT_HOOK_NAME);
         const foreignHookPath = join(gitHooksDirectory, FOREIGN_HOOK_NAME);
         const foreignHookContentBytes = Buffer.from('foreign hook content\n', 'utf8');
-        writeFileWithParents(postCommitShimPath, 'generated by an earlier install\n');
+        const staleShimContent = 'generated by an earlier install\n';
+        writeFileWithParents(postCommitShimPath, staleShimContent);
         writeFileWithParents(foreignHookPath, foreignHookContentBytes);
         appendManifestFiles(sandbox.manifestPath, [postCommitShimPath]);
 
         runInstaller(sandbox.homeDirectory, []);
 
         const freshManifest = readManifest(sandbox.manifestPath);
-        assert.equal(existsSync(postCommitShimPath), false);
+        assert.notEqual(readFileSync(postCommitShimPath, 'utf8'), staleShimContent);
         assert.deepEqual(readFileSync(foreignHookPath), foreignHookContentBytes);
-        assert.equal(freshManifest.files.includes(postCommitShimPath), false);
         assert.equal(freshManifest.files.includes(foreignHookPath), false);
-        for (const gitHookName of [PRE_COMMIT_HOOK_NAME, PRE_PUSH_HOOK_NAME]) {
+        for (const gitHookName of [PRE_COMMIT_HOOK_NAME, PRE_PUSH_HOOK_NAME, POST_COMMIT_HOOK_NAME]) {
             const generatedShimPath = join(gitHooksDirectory, gitHookName);
             assert.equal(existsSync(generatedShimPath), true);
             assert.equal(freshManifest.files.includes(generatedShimPath), true);
@@ -1050,7 +1088,7 @@ test('a reinstall removes a retired post-commit shim and preserves a foreign git
     }
 });
 
-test('a full reinstall drops a retired hook script and its settings entry in one run', () => {
+test('a full reinstall retires a hook script and leaves an inert stand-in the open session can still run', () => {
     const sandbox = createSandbox();
     try {
         runInstaller(sandbox.homeDirectory, []);
@@ -1058,9 +1096,26 @@ test('a full reinstall drops a retired hook script and its settings entry in one
             retiredHookPath, retiredHookCommand, lookalikeHookCommand,
         } = seedRetiredManagedHook(sandbox);
 
-        runInstaller(sandbox.homeDirectory, []);
+        const installOutput = runInstallerReadingBothStreams(sandbox.homeDirectory, []);
 
-        assert.equal(existsSync(retiredHookPath), false, 'the retired hook script leaves ~/.claude/hooks');
+        assert.notEqual(
+            readFileSync(retiredHookPath, 'utf8'),
+            RETIRED_HOOK_SEEDED_CONTENTS,
+            'the retired gate itself no longer runs at that path',
+        );
+        const standInRun = spawnSync(detectPython(), [retiredHookPath], { encoding: 'utf8' });
+        assert.equal(
+            standInRun.status,
+            0,
+            'a session holding the old registration runs the stand-in and gets an allow',
+        );
+        assert.equal(standInRun.stdout, '', 'the stand-in writes nothing to stdout');
+        assert.equal(standInRun.stderr, '', 'the stand-in writes nothing to stderr');
+        assert.match(
+            installOutput,
+            /Restart open sessions: this install retired blocking\/retired_gate\.py/,
+            'the run names the retired registration and asks for a restart',
+        );
         assert.equal(
             prunedBackupContains(
                 sandbox.claudeDirectory, join(HOOKS_DIRECTORY_NAME, ...RETIRED_HOOK_RELATIVE_SEGMENTS),
@@ -1084,6 +1139,59 @@ test('a full reinstall drops a retired hook script and its settings entry in one
             true,
             'a user command whose path is the retired tail plus a suffix names another file and stays',
         );
+
+        runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            existsSync(retiredHookPath),
+            false,
+            'the next run finds no registration naming the stand-in, so the stand-in leaves too',
+        );
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+test('a full reinstall leaves a stand-in for a registration the package itself stopped shipping', () => {
+    const sandbox = createSandbox();
+    try {
+        runInstaller(sandbox.homeDirectory, []);
+        const retiredHookPath = join(
+            sandbox.claudeDirectory,
+            HOOKS_DIRECTORY_NAME,
+            ...FOLDED_RETIRED_HOOK_RELATIVE_SEGMENTS,
+        );
+        writeFileWithParents(retiredHookPath, RETIRED_HOOK_SEEDED_CONTENTS);
+        appendManifestFiles(sandbox.manifestPath, [retiredHookPath]);
+        const retiredHookCommand = `python3 "${retiredHookPath.replace(/\\/g, '/')}"`;
+        const settings = readSettings(sandbox.claudeDirectory);
+        settings.hooks[RETIRED_HOOK_EVENT_TYPE].push({
+            matcher: 'AskUserQuestion',
+            hooks: [{ type: 'command', command: retiredHookCommand }],
+        });
+        writeFileSync(
+            join(sandbox.claudeDirectory, SETTINGS_FILE_NAME),
+            JSON.stringify(settings, null, 4) + '\n',
+        );
+
+        const installOutput = runInstallerReadingBothStreams(sandbox.homeDirectory, []);
+
+        assert.equal(
+            allHookCommands(readSettings(sandbox.claudeDirectory)).includes(retiredHookCommand),
+            false,
+            'the registration the package stopped shipping leaves settings.json',
+        );
+        const standInRun = spawnSync(detectPython(), [retiredHookPath], { encoding: 'utf8' });
+        assert.equal(
+            standInRun.status,
+            0,
+            'a session still holding that registration runs a stand-in and gets an allow',
+        );
+        assert.match(
+            installOutput,
+            /Restart open sessions: this install retired blocking\/ask_user_question_shape_blocker\.py/,
+            'the run names the registration the merge would otherwise drop in silence',
+        );
     } finally {
         rmSync(sandbox.homeDirectory, { recursive: true, force: true });
     }
@@ -1189,7 +1297,23 @@ test('a full reinstall removes retired pull request hooks and preserves foreign
 
         const freshManifest = readManifest(sandbox.manifestPath);
         const allCommands = allHookCommands(readSettings(sandbox.claudeDirectory));
-        for (const retiredPath of retiredPaths) {
+        const registeredRetiredPaths = new Set(RETIRED_PULL_REQUEST_REGISTRATION_PATHS);
+        for (const relativePath of RETIRED_PULL_REQUEST_HOOK_RELATIVE_PATHS) {
+            const retiredPath = join(
+                sandbox.claudeDirectory, HOOKS_DIRECTORY_NAME, ...relativePath.split('/'),
+            );
+            if (registeredRetiredPaths.has(relativePath)) {
+                assert.equal(
+                    spawnSync(detectPython(), [retiredPath], { encoding: 'utf8' }).status,
+                    0,
+                    `${relativePath} keeps an inert stand-in while a session still registers it`,
+                );
+                assert.ok(
+                    freshManifest.files.includes(retiredPath),
+                    `${relativePath} is recorded, so a later run retires the stand-in`,
+                );
+                continue;
+            }
             assert.equal(existsSync(retiredPath), false, `${retiredPath} leaves installed hooks`);
             assert.equal(freshManifest.files.includes(retiredPath), false);
         }
@@ -1203,6 +1327,131 @@ test('a full reinstall removes retired pull request hooks and preserves foreign
     }
 });
 
+
+const CODEX_DIRECTORY_NAME = '.codex';
+const CODEX_HOOKS_CONFIGURATION_FILE_NAME = 'hooks.json';
+const FOREIGN_TOOL_DIRECTORY_NAME = 'other-tool';
+const FOREIGN_CODEX_HOOK_COMMAND = 'python3 my_own_codex_gate.py --user-authored';
+
+
+/**
+ * Build the command one hook registration runs for a script under a hooks root.
+ *
+ * @param {string} hooksRoot The hooks directory the registration names.
+ * @param {string[]} relativeSegments The script path segments under that directory.
+ * @returns {string} The registration command.
+ */
+function hookCommandUnder(hooksRoot, relativeSegments) {
+    return `python3 "${join(hooksRoot, ...relativeSegments).replace(/\\/g, '/')}"`;
+}
+
+
+/**
+ * Write a Codex hooks file registering one retired script beside a foreign entry.
+ *
+ * @param {{homeDirectory: string}} sandbox The sandbox paths.
+ * @returns {{codexHooksPath: string, codexRetiredCommand: string}} The file and its retired entry.
+ */
+function seedCodexHookRegistrations(sandbox) {
+    const codexDirectory = join(sandbox.homeDirectory, CODEX_DIRECTORY_NAME);
+    const codexHooksPath = join(codexDirectory, CODEX_HOOKS_CONFIGURATION_FILE_NAME);
+    const codexRetiredCommand = hookCommandUnder(
+        join(codexDirectory, HOOKS_DIRECTORY_NAME), RETIRED_HOOK_RELATIVE_SEGMENTS,
+    );
+    writeFileWithParents(codexHooksPath, JSON.stringify({
+        hooks: {
+            [RETIRED_HOOK_EVENT_TYPE]: [{
+                matcher: 'Bash',
+                hooks: [
+                    { type: 'command', command: codexRetiredCommand },
+                    { type: 'command', command: FOREIGN_CODEX_HOOK_COMMAND },
+                ],
+            }],
+        },
+    }, null, 4) + '\n');
+    return { codexHooksPath, codexRetiredCommand };
+}
+
+
+test('a full reinstall prunes a retired registration the Codex hooks file holds and leaves a stand-in', () => {
+    const sandbox = createSandbox();
+    try {
+        runInstaller(sandbox.homeDirectory, []);
+        const retiredHookPath = join(
+            sandbox.claudeDirectory, HOOKS_DIRECTORY_NAME, ...RETIRED_HOOK_RELATIVE_SEGMENTS,
+        );
+        writeFileWithParents(retiredHookPath, RETIRED_HOOK_SEEDED_CONTENTS);
+        appendManifestFiles(sandbox.manifestPath, [retiredHookPath]);
+        const { codexHooksPath, codexRetiredCommand } = seedCodexHookRegistrations(sandbox);
+
+        const installOutput = runInstallerReadingBothStreams(sandbox.homeDirectory, []);
+
+        const codexCommands = allHookCommands(JSON.parse(readFileSync(codexHooksPath, 'utf8')));
+        assert.equal(
+            codexCommands.includes(codexRetiredCommand),
+            false,
+            'the Codex registration naming the retired script is pruned like a settings.json one',
+        );
+        assert.equal(
+            codexCommands.includes(FOREIGN_CODEX_HOOK_COMMAND),
+            true,
+            'the user-authored Codex entry sharing the matcher group survives',
+        );
+        assert.equal(
+            spawnSync(detectPython(), [retiredHookPath], { encoding: 'utf8' }).status,
+            0,
+            'the Codex registration alone earns the retired path an inert stand-in',
+        );
+        assert.match(
+            installOutput,
+            /Restart open sessions: this install retired blocking\/retired_gate\.py/,
+            'the run names the retired registration and asks for a restart',
+        );
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
+
+test('a full reinstall leaves a registration under a hooks root the installer does not own', () => {
+    const sandbox = createSandbox();
+    try {
+        runInstaller(sandbox.homeDirectory, []);
+        seedRetiredManagedHook(sandbox);
+        const foreignHooksRoot = join(
+            sandbox.homeDirectory, FOREIGN_TOOL_DIRECTORY_NAME, '.claude', HOOKS_DIRECTORY_NAME,
+        );
+        const foreignHookPath = join(foreignHooksRoot, ...RETIRED_HOOK_RELATIVE_SEGMENTS);
+        const foreignHookBytes = Buffer.from('another tool owns this gate\n', 'utf8');
+        writeFileWithParents(foreignHookPath, foreignHookBytes);
+        const foreignCommand = hookCommandUnder(foreignHooksRoot, RETIRED_HOOK_RELATIVE_SEGMENTS);
+        const settings = readSettings(sandbox.claudeDirectory);
+        settings.hooks[RETIRED_HOOK_EVENT_TYPE].push({
+            matcher: 'Bash',
+            hooks: [{ type: 'command', command: foreignCommand }],
+        });
+        writeFileSync(
+            join(sandbox.claudeDirectory, SETTINGS_FILE_NAME),
+            JSON.stringify(settings, null, 4) + '\n',
+        );
+
+        runInstaller(sandbox.homeDirectory, []);
+
+        assert.equal(
+            allHookCommands(readSettings(sandbox.claudeDirectory)).includes(foreignCommand),
+            true,
+            'a registration whose hooks root the installer does not own keeps its entry',
+        );
+        assert.deepEqual(
+            readFileSync(foreignHookPath),
+            foreignHookBytes,
+            'the foreign script keeps its own bytes, so no stand-in replaced it',
+        );
+    } finally {
+        rmSync(sandbox.homeDirectory, { recursive: true, force: true });
+    }
+});
+
 test('a full reinstall removes a retired hook entry under an event type the current config leaves out', () => {
     const sandbox = createSandbox();
     try {