claude-dev-env 8.88.3 → 8.88.4

package/bin/install.mjs

@@ -133,6 +133,8 @@ import {
     addOpenTasksGateToProfiles,
     otherProfileSettingsPaths,
     removeOpenTasksGateFromProfiles,
+    splitUnreadableProfileSettings,
+    unparsedSettingsMayHoldGate,
 } from './profile-stop-gate.mjs';
 import { pythonExecutableProbeCommand } from './python-probe.mjs';
 
@@ -2714,6 +2716,54 @@ function profileSettingsPathsForStopGate(mainSettingsPath) {
     return otherProfileSettingsPaths({ homeDirectory: homedir(), environment: process.env, mainSettingsPath });
 }
 
+/**
+ * Return the profile settings the gate step can parse, and add an Action needed line for each one it cannot.
+ *
+ * @param {string} mainSettingsPath
+ * @returns {string[]}
+ */
+function readableProfileSettingsPathsForStopGate(mainSettingsPath) {
+    const { allReadablePaths, allUnreadable } = splitUnreadableProfileSettings(
+        profileSettingsPathsForStopGate(mainSettingsPath),
+    );
+    for (const { settingsPath, reason } of allUnreadable) {
+        const actionLine = `Profile settings: ${settingsPath} was left unchanged because it is not valid JSON (${reason}).`
+            + ' Fix the file and run the install again to add the open-tasks Stop gate there.';
+        console.warn(`  ${actionLine}`);
+        allActionNeededLines.push(actionLine);
+    }
+    return allReadablePaths;
+}
+
+/**
+ * Return the profile settings the uninstall removes the gate from, or the reason it must stop first.
+ *
+ * A profile file that does not parse and may still hold the gate stops the
+ * uninstall before it changes anything. The manifest then stays, so running
+ * --uninstall again after fixing the file removes the gate. A file that does
+ * not parse and does not name the gate has nothing to remove and is left as
+ * it is.
+ *
+ * @param {string} mainSettingsPath
+ * @returns {{ allReadablePaths: string[], blockingReason: string|null }}
+ */
+function profileSettingsPathsForGateRemoval(mainSettingsPath) {
+    const { allReadablePaths, allUnreadable } = splitUnreadableProfileSettings(
+        profileSettingsPathsForStopGate(mainSettingsPath),
+    );
+    const allHoldingGate = allUnreadable.filter(
+        ({ settingsPath }) => unparsedSettingsMayHoldGate(settingsPath, CLAUDE_HOME),
+    );
+    if (allHoldingGate.length === 0) return { allReadablePaths, blockingReason: null };
+    const fileLines = allHoldingGate.map(({ settingsPath, reason }) => `  ${settingsPath}: not valid JSON (${reason})`);
+    const blockingReason = [
+        'ERROR: uninstall stopped before changing anything. These profile settings files still name the open-tasks Stop gate, and they are not valid JSON, so the gate cannot be removed from them:',
+        ...fileLines,
+        'Fix each file and run --uninstall again.',
+    ].join('\n');
+    return { allReadablePaths, blockingReason };
+}
+
 function executeInstallPlan(plan) {
     const faultPhase = resolveFaultPhaseFromEnvironment(process.env);
     const snapshot = capturePriorInstallSnapshot({
@@ -3208,7 +3258,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     for (const eachOutcome of addOpenTasksGateToProfiles({
         mainSettingsPath: join(CLAUDE_HOME, SETTINGS_FILE_NAME),
         claudeHome: CLAUDE_HOME,
-        allProfileSettingsPaths: profileSettingsPathsForStopGate(join(CLAUDE_HOME, SETTINGS_FILE_NAME)),
+        allProfileSettingsPaths: readableProfileSettingsPathsForStopGate(join(CLAUDE_HOME, SETTINGS_FILE_NAME)),
         homeDirectory: homedir(),
     })) {
         if (eachOutcome.additions.length > 0) {
@@ -3498,7 +3548,7 @@ function executeUninstallPlan(plan, helpers = {}) {
     }
     for (const eachChangedPath of removeOpenTasksGateFromProfiles({
         claudeHome: CLAUDE_HOME,
-        allProfileSettingsPaths: profileSettingsPathsForStopGate(plan.settingsPath),
+        allProfileSettingsPaths: helpers.allProfileSettingsPaths,
     })) {
         console.log(`  Profile settings: open-tasks Stop gate removed from ${eachChangedPath}`);
     }
@@ -3554,6 +3604,11 @@ function uninstall() {
     if (plan.isNoOp) {
         return;
     }
+    const gateRemoval = profileSettingsPathsForGateRemoval(plan.settingsPath);
+    if (gateRemoval.blockingReason) {
+        console.error(gateRemoval.blockingReason);
+        process.exit(1);
+    }
 
     const faultPhase = resolveFaultPhaseFromEnvironment(process.env);
     const snapshot = capturePriorInstallSnapshot({
@@ -3576,7 +3631,7 @@ function uninstall() {
             snapshot,
             faultPhase,
             runMutations: ({ throwIfFault }) => {
-                executeUninstallPlan(plan, { throwIfFault });
+                executeUninstallPlan(plan, { throwIfFault, allProfileSettingsPaths: gateRemoval.allReadablePaths });
             },
         });
     } catch (mutationError) {

package/bin/install.test.mjs

@@ -3726,3 +3726,104 @@ test('install adds the open-tasks Stop gate to every profile with its own settin
     assert.equal(uninstallation.status, 0, uninstallation.stderr);
     assert.deepEqual(JSON.parse(readFileSync(profileSettingsPath, 'utf8')), { outputStyle: 'plain' });
 });
+
+test('a profile settings.json that is not valid JSON is left alone and named under Action needed, and the rest of the install and uninstall go through', (context) => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-profile-gate-malformed-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    const brokenSettingsPath = join(homeDirectory, '.claude-profiles', 'broken', 'settings.json');
+    const goodSettingsPath = join(homeDirectory, '.claude-profiles', 'good', 'settings.json');
+    const brokenSettingsText = '{"hooks":{},}\n';
+    mkdirSync(dirname(brokenSettingsPath), { recursive: true });
+    mkdirSync(dirname(goodSettingsPath), { recursive: true });
+    writeFileSync(brokenSettingsPath, brokenSettingsText);
+    writeFileSync(goodSettingsPath, JSON.stringify({ outputStyle: 'plain' }, null, 4));
+    const runInstaller = (argumentsList) => spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'install.mjs'), ...argumentsList], {
+        cwd: dirname(dirname(fileURLToPath(import.meta.url))),
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            CLAUDE_CONFIG_DIR: undefined,
+            LLM_SETTINGS_PROFILES_ROOT: undefined,
+            CLAUDE_DEV_ENV_INSTALL_FAULT: undefined,
+            CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_DEEPSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
+            CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            TEMP: homeDirectory,
+            TMP: homeDirectory,
+        },
+    });
+    const goodGateCount = () => (JSON.parse(readFileSync(goodSettingsPath, 'utf8')).hooks?.Stop ?? [])
+        .flatMap((eachGroup) => eachGroup.hooks.map((eachHook) => eachHook.command))
+        .filter((eachCommand) => eachCommand.includes('open_tasks_stop_gate.py')).length;
+    const actionNeededSection = (stderrText) => stderrText.slice(stderrText.indexOf('Action needed'));
+
+    const installation = runInstaller([]);
+    assert.equal(installation.status, 0, installation.stderr);
+    assert.equal(readFileSync(brokenSettingsPath, 'utf8'), brokenSettingsText);
+    assert.equal(goodGateCount(), 1);
+    assert.match(actionNeededSection(installation.stderr), /Action needed \(1\):/);
+    assert.ok(actionNeededSection(installation.stderr).includes(brokenSettingsPath));
+    assert.match(actionNeededSection(installation.stderr), /not valid JSON \(.+\)/);
+
+    const uninstallation = runInstaller(['--uninstall']);
+    assert.equal(uninstallation.status, 0, uninstallation.stderr);
+    assert.equal(readFileSync(brokenSettingsPath, 'utf8'), brokenSettingsText);
+    assert.equal(goodGateCount(), 0);
+});
+
+test('uninstall stops before changing anything while a profile settings.json that is not valid JSON still names the gate, and a rerun after the fix removes it', (context) => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-profile-gate-uninstall-malformed-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    const profileSettingsPath = join(homeDirectory, '.claude-profiles', 'prefs-only', 'settings.json');
+    mkdirSync(dirname(profileSettingsPath), { recursive: true });
+    writeFileSync(profileSettingsPath, JSON.stringify({ outputStyle: 'plain' }, null, 4));
+    const runInstaller = (argumentsList) => spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'install.mjs'), ...argumentsList], {
+        cwd: dirname(dirname(fileURLToPath(import.meta.url))),
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            CLAUDE_CONFIG_DIR: undefined,
+            LLM_SETTINGS_PROFILES_ROOT: undefined,
+            CLAUDE_DEV_ENV_INSTALL_FAULT: undefined,
+            CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_DEEPSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
+            CDE_INSTALL_DEEPEN_FIRST_PROMPT: '0',
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            TEMP: homeDirectory,
+            TMP: homeDirectory,
+        },
+    });
+    const manifestPath = join(homeDirectory, '.claude', '.claude-dev-env-manifest.json');
+
+    const installation = runInstaller([]);
+    assert.equal(installation.status, 0, installation.stderr);
+    const validText = readFileSync(profileSettingsPath, 'utf8');
+    assert.ok(validText.includes('open_tasks_stop_gate.py'));
+    const brokenText = validText.trimEnd().replace(/\}$/, ',}') + '\n';
+    writeFileSync(profileSettingsPath, brokenText);
+
+    const stoppedUninstall = runInstaller(['--uninstall']);
+    assert.equal(stoppedUninstall.status, 1, stoppedUninstall.stdout);
+    assert.ok(stoppedUninstall.stderr.includes(profileSettingsPath), stoppedUninstall.stderr);
+    assert.match(stoppedUninstall.stderr, /not valid JSON \(.+\)/);
+    assert.match(stoppedUninstall.stderr, /run --uninstall again/);
+    assert.equal(readFileSync(profileSettingsPath, 'utf8'), brokenText);
+    assert.ok(existsSync(manifestPath));
+
+    writeFileSync(profileSettingsPath, validText);
+    const rerunUninstall = runInstaller(['--uninstall']);
+    assert.equal(rerunUninstall.status, 0, rerunUninstall.stderr);
+    assert.deepEqual(JSON.parse(readFileSync(profileSettingsPath, 'utf8')), { outputStyle: 'plain' });
+    assert.equal(existsSync(manifestPath), false);
+});

package/bin/profile-stop-gate.mjs

@@ -82,6 +82,55 @@ export function otherProfileSettingsPaths(options) {
     return allOtherPaths;
 }
 
+/**
+ * Split profile settings paths into the ones whose settings.json parses and the ones that do not.
+ *
+ * A profile file that is not valid JSON is left as it is. The caller names
+ * each one, with its parse error, so the user can fix it and run the install
+ * again. An empty file counts as readable.
+ *
+ * @param {string[]} allProfileSettingsPaths
+ * @returns {{ allReadablePaths: string[], allUnreadable: { settingsPath: string, reason: string }[] }}
+ */
+export function splitUnreadableProfileSettings(allProfileSettingsPaths) {
+    const allReadablePaths = [];
+    const allUnreadable = [];
+    for (const eachPath of allProfileSettingsPaths) {
+        try {
+            const settingsText = readFileSync(eachPath, 'utf8');
+            if (settingsText.trim()) JSON.parse(settingsText);
+            allReadablePaths.push(eachPath);
+        } catch (readError) {
+            allUnreadable.push({
+                settingsPath: eachPath,
+                reason: readError instanceof Error ? readError.message : String(readError),
+            });
+        }
+    }
+    return { allReadablePaths, allUnreadable };
+}
+
+/**
+ * True when a settings.json that does not parse may still hold this Claude home's open-tasks gate.
+ *
+ * The raw text is searched for the gate script path, with JSON-escaped
+ * backslashes read as path separators. A file that cannot be read counts as
+ * one that may hold the gate.
+ *
+ * @param {string} settingsPath
+ * @param {string} claudeHome
+ * @returns {boolean}
+ */
+export function unparsedSettingsMayHoldGate(settingsPath, claudeHome) {
+    let settingsText;
+    try {
+        settingsText = readFileSync(settingsPath, 'utf8');
+    } catch {
+        return true;
+    }
+    return comparableCommand(settingsText.replace(/\\\\/g, '/')).includes(gateScriptCommandFragment(claudeHome));
+}
+
 function stopHooks(settingsPath) {
     const settingsText = readFileSync(settingsPath, 'utf8');
     if (!settingsText.trim()) return [];

package/bin/profile-stop-gate.test.mjs

@@ -8,6 +8,8 @@ import {
     addOpenTasksGateToProfiles,
     otherProfileSettingsPaths,
     removeOpenTasksGateFromProfiles,
+    splitUnreadableProfileSettings,
+    unparsedSettingsMayHoldGate,
 } from './profile-stop-gate.mjs';
 
 function makeHome(context) {
@@ -122,3 +124,37 @@ test('a profile that already runs its own copy of the gate script gets no second
     assert.deepEqual(allOutcomes, []);
     assert.deepEqual(stopCommands(profilePath), [ownGateCommand]);
 });
+
+test('a settings.json that is not valid JSON is reported with its parse error, and an empty one counts as readable', (context) => {
+    const { homeDirectory } = makeHome(context);
+    const goodPath = writeProfile(homeDirectory, 'good', { outputStyle: 'plain' });
+    const emptyPath = writeProfile(homeDirectory, 'empty');
+    writeFileSync(emptyPath, '');
+    const brokenPath = writeProfile(homeDirectory, 'broken');
+    writeFileSync(brokenPath, '{"hooks":{},}');
+
+    const { allReadablePaths, allUnreadable } = splitUnreadableProfileSettings([goodPath, emptyPath, brokenPath]);
+
+    assert.deepEqual(allReadablePaths, [goodPath, emptyPath]);
+    assert.equal(allUnreadable.length, 1);
+    assert.equal(allUnreadable[0].settingsPath, brokenPath);
+    assert.match(allUnreadable[0].reason, /JSON/);
+});
+
+test('a settings.json that does not parse may hold the gate when its text names this home\'s gate script, in either slash spelling', (context) => {
+    const { homeDirectory, claudeHome, gateCommand } = makeHome(context);
+    const forwardPath = writeProfile(homeDirectory, 'forward');
+    writeFileSync(forwardPath, `{"hooks":{"Stop":[{"hooks":[{"command":"${gateCommand}"}]}]},}`);
+    const escapedPath = writeProfile(homeDirectory, 'escaped');
+    writeFileSync(escapedPath, `{"hooks":{"Stop":[{"hooks":[{"command":"${gateCommand.replace(/\//g, '\\\\')}"}]}]},}`);
+    const otherHomePath = writeProfile(homeDirectory, 'other-home');
+    writeFileSync(otherHomePath, '{"hooks":{"Stop":[{"hooks":[{"command":"python3 /opt/other/.claude/hooks/blocking/open_tasks_stop_gate.py"}]}]},}');
+    const noGatePath = writeProfile(homeDirectory, 'no-gate');
+    writeFileSync(noGatePath, '{"hooks":{},}');
+
+    assert.equal(unparsedSettingsMayHoldGate(forwardPath, claudeHome), true);
+    assert.equal(unparsedSettingsMayHoldGate(escapedPath, claudeHome), true);
+    assert.equal(unparsedSettingsMayHoldGate(otherHomePath, claudeHome), false);
+    assert.equal(unparsedSettingsMayHoldGate(noGatePath, claudeHome), false);
+    assert.equal(unparsedSettingsMayHoldGate(join(homeDirectory, 'missing', 'settings.json'), claudeHome), true);
+});

package/docs/agents-guidance/asks.md

@@ -25,7 +25,7 @@ When the host keeps an asks ledger with `ledger.py` and `asks_check.py`, record
 
 The installer registers `open_tasks_stop_gate.py` as a Stop hook for each host:
 
-- Claude Code: `hooks.json`. A block returns the open items as the reason, and the session keeps working. An install into `~/.claude` also adds the same Stop entry to every profile under `~/.claude-profiles` that has its own `settings.json` and does not already run its own copy of the gate. A profile whose `settings.json` links to `~/.claude/settings.json` already has it. Uninstall removes only that entry.
+- Claude Code: `hooks.json`. A block returns the open items as the reason, and the session keeps working. An install into `~/.claude` also adds the same Stop entry to every profile under `~/.claude-profiles` that has its own `settings.json` and does not already run its own copy of the gate. A profile whose `settings.json` links to `~/.claude/settings.json` already has it. Uninstall removes only that entry. On install, a profile `settings.json` that is not valid JSON is left unchanged and listed under Action needed with its path and parse error, and the rest of the install goes on. On uninstall, such a file that still names the gate stops the uninstall before anything changes, so the manifest stays and a rerun after the fix removes the gate; one that does not name the gate is left as it is.
 - Codex: `$CODEX_HOME/hooks.json`. Codex turns the reason into a continuation prompt.
 - Cursor: a native `stop` entry in `~/.cursor/hooks.json`. The reason comes back as `followup_message`, the next user message. A stop with status `aborted` or `error` passes, so a turn the user cancels stays silent.
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "claude-dev-env",
-    "version": "8.88.3",
+    "version": "8.88.4",
     "description": "Claude Code development standards — rules, hooks, agents, commands, and skills",
     "type": "module",
     "bin": {