claude-dev-env 8.88.0 → 8.88.2

package/bin/install-pstack-plugin.mjs

@@ -1,6 +1,7 @@
 import { spawnSync } from 'node:child_process';
 import { existsSync, readdirSync, rmSync } from 'node:fs';
 import { join } from 'node:path';
+import { findFolderLockers, lockedFolderAdvice, namesALockedFolder } from './folder-lockers.mjs';
 
 export const PSTACK_MARKETPLACE_REPOSITORY = 'jl-cmd/pstack-claude';
 export const PSTACK_MARKETPLACE_NAME = 'pstack-claude';
@@ -248,7 +249,17 @@ function absentHostOutcome(allSpecs, host, executable) {
     };
 }
 
-function installForHost(allSpecs, host, homeDirectory, environment, runCommand) {
+function lockedFolderDetail(allSpecs, host, homeDirectory, errorText, findLockers) {
+    const hostDefinition = HOST_DEFINITIONS[host];
+    if (!namesALockedFolder(errorText) || !hostDefinition.orphanedVersionsDirectory || !homeDirectory) return '';
+    return allSpecs.map(eachSpec => {
+        const pluginCacheDirectory = hostDefinition.orphanedVersionsDirectory(homeDirectory, eachSpec);
+        const allLockers = findLockers(pluginCacheDirectory);
+        return allLockers === null ? '' : ` ${lockedFolderAdvice(pluginCacheDirectory, allLockers)}`;
+    }).join('');
+}
+
+function installForHost(allSpecs, host, homeDirectory, environment, runCommand, findLockers) {
     const plan = marketplacePluginsPlan(allSpecs, host);
     const executable = environment[plan.executableVariable] || plan.executable;
     const commandEnvironment = { [plan.homeVariable]: homeDirectory };
@@ -265,11 +276,12 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand)
         if (namesAnAbsentCommand(outcome)) return absentHostOutcome(allSpecs, host, executable);
         if (outcome.status !== 0 || outcome.error) {
             const detail = singleLineDetail(outcome.stderr) || outcome.error?.message || `exit ${outcome.status}`;
+            const lockAdvice = lockedFolderDetail(allSpecs, host, homeDirectory, detail, findLockers);
             return {
                 host,
                 executable,
                 status: 'failed',
-                warning: `${executable} ${commandArguments.join(' ')} failed: ${detail}`,
+                warning: `${executable} ${commandArguments.join(' ')} failed: ${detail}${lockAdvice}`,
             };
         }
     }
@@ -294,7 +306,9 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand)
  * and skills this run already wrote still reach their durable places. An
  * absent tool arrives as a spawn `ENOENT` on other platforms and as
  * `cmd.exe`'s command-not-found exit code on Windows, and both read as
- * skipped.
+ * skipped. When a host cannot replace a plugin folder because something holds
+ * it, the warning names each process that holds it, so the user knows what to
+ * close before running the install again.
  *
  * @param {ReadonlyArray<typeof PSTACK_PLUGIN_SPEC>} allSpecs The plugins to install, from one marketplace.
  * @param {object} [options] Install targets.
@@ -302,12 +316,13 @@ function installForHost(allSpecs, host, homeDirectory, environment, runCommand)
  * @param {string} [options.codexHome] The Codex home to install into.
  * @param {string[]} [options.hosts] The hosts to install. Defaults to the hosts every spec names.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
- * @param {object} [dependencies] Seams for the command runner.
+ * @param {object} [dependencies] Seams for the command runner and the folder locker search.
  * @returns {{status: string, hosts: object[], warning: string|null}} The outcome per host.
  */
 export function installMarketplacePlugins(allSpecs, options = {}, dependencies = {}) {
     const environment = options.environment ?? process.env;
     const runCommand = dependencies.runCommand ?? runHostCommand;
+    const findLockers = dependencies.findLockers ?? findFolderLockers;
     const homeDirectories = { claude: options.claudeRoot, codex: options.codexHome };
     const hosts = options.hosts ?? allSpecs[0].hosts.filter(
         eachHost => allSpecs.every(eachSpec => eachSpec.hosts.includes(eachHost)),
@@ -318,6 +333,7 @@ export function installMarketplacePlugins(allSpecs, options = {}, dependencies =
         homeDirectories[host],
         environment,
         runCommand,
+        findLockers,
     ));
     const failedCount = hostOutcomes.filter(outcome => outcome.status === 'failed').length;
     const installedCount = hostOutcomes.filter(outcome => outcome.status === 'installed').length;

package/bin/install-pstack-plugin.test.mjs

@@ -392,3 +392,56 @@ test('a clean install deletes the orphaned pstack versions and keeps the install
     assert.equal(existsSync(join(versionsDirectory, '0.9.64')), true);
     assert.deepEqual(removeOrphanedPluginVersions(versionsDirectory), []);
 });
+
+test('a plugin folder held by another program names the process to close', () => {
+    const lockedError = 'Failed to install plugin "pstack@pstack-claude": The installed copy of this plugin version'
+        + ' could not be replaced: it is in use by another program (EPERM).';
+    const searchedFolders = [];
+    const runner = recordingRunner((executable, commandArguments) => (
+        executable === 'claude' && commandArguments[1] === 'install'
+            ? { status: 1, stderr: lockedError }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        runCommand: runner.runCommand,
+        findLockers: folderPath => {
+            searchedFolders.push(folderPath);
+            return [{ pid: 19056, name: 'Cursor.exe', reason: 'command-line' }];
+        },
+    });
+    const claude = outcome.hosts.find(host => host.host === 'claude');
+    assert.equal(claude.status, 'failed');
+    assert.deepEqual(searchedFolders, [join('/managed/.claude', 'plugins', 'cache', 'pstack-claude', 'pstack')]);
+    assert.match(claude.warning, /Close Cursor\.exe \(PID 19056, was started on a path inside it\)/);
+});
+
+test('a failure that is not a held folder runs no locker search', () => {
+    const runner = recordingRunner((executable, commandArguments) => (
+        executable === 'claude' && commandArguments[2] === 'add'
+            ? { status: 1, stderr: 'owner: Invalid input: expected object, received undefined' }
+            : { status: 0, stderr: '' }));
+    let searched = false;
+    installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        runCommand: runner.runCommand,
+        findLockers: () => {
+            searched = true;
+            return [];
+        },
+    });
+    assert.equal(searched, false);
+});
+
+test('a held folder that was not searched adds no claim about what holds it', () => {
+    const lockedError = 'Failed to install plugin "pstack@pstack-claude": EPERM: operation not permitted';
+    const runner = recordingRunner((executable, commandArguments) => (
+        executable === 'claude' && commandArguments[1] === 'install'
+            ? { status: 1, stderr: lockedError }
+            : { status: 0, stderr: '' }));
+    const outcome = installMarketplacePlugins([PSTACK_PLUGIN_SPEC], ROOTS, {
+        runCommand: runner.runCommand,
+        findLockers: () => null,
+    });
+    const claude = outcome.hosts.find(host => host.host === 'claude');
+    assert.equal(claude.status, 'failed');
+    assert.match(claude.warning, /EPERM: operation not permitted$/);
+    assert.doesNotMatch(claude.warning, /likely holder|Close /);
+});

package/bin/install.mjs

@@ -72,7 +72,9 @@ import {
     writeCursorAgentsGuidanceHooks,
 } from './cursor-agents-guidance.mjs';
 import {
+    codexSolPromptPath,
     codexSolSettingSnapshotPaths,
+    installCodexSolPrompt,
     removeCodexSolSetting,
     SOL_PROMPT_DIRECTORY_NAME,
     SOL_PROMPT_FILE_NAME,
@@ -126,6 +128,8 @@ import {
     resolveFaultPhaseFromEnvironment,
     runWithInstallTransaction,
 } from './install-transaction.mjs';
+import { findShadowingGlobalInstall, shadowingGlobalAdvice } from './global-install-shadow.mjs';
+import { pythonExecutableProbeCommand } from './python-probe.mjs';
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const INSTALL_ROOT_RESOLUTION = resolveInstallRoot({
@@ -442,16 +446,28 @@ export function installPstackPluginForHosts() {
     });
 }
 
+/** Side steps that need the user, repeated at the end of the run so none scrolls past unseen. */
+const allActionNeededLines = [];
+
 function printPluginHostOutcomes(allSpecs, pluginOutcome) {
     for (const eachSpec of allSpecs) {
         for (const eachHost of pluginOutcome.hosts) {
-            console.log(eachHost.warning
-                ? `  ${eachSpec.label} (${eachHost.host}): ${eachHost.status} — ${eachHost.warning}`
-                : `  ${eachSpec.label} (${eachHost.host}): ${eachHost.status}`);
+            const outcomeLine = eachHost.warning
+                ? `${eachSpec.label} (${eachHost.host}): ${eachHost.status} — ${eachHost.warning}`
+                : `${eachSpec.label} (${eachHost.host}): ${eachHost.status}`;
+            console.log(`  ${outcomeLine}`);
+            if (eachHost.status === 'failed') allActionNeededLines.push(outcomeLine);
         }
     }
 }
 
+function printActionNeeded() {
+    if (allActionNeededLines.length === 0) return;
+    console.warn(`Action needed (${allActionNeededLines.length}):`);
+    for (const eachLine of allActionNeededLines) console.warn(`  - ${eachLine}`);
+    console.warn('');
+}
+
 function seedSubagentModelPolicy() {
     const policyDirectory = join(AGENTS_HOME, CURSOR_RULES_DIRECTORY_NAME);
     const policyPath = join(policyDirectory, SUBAGENT_MODEL_POLICY_FILE_NAME);
@@ -550,7 +566,9 @@ function quoteStandalonePluginRootHookPath(commandString, pluginRootForward) {
  * sys.executable and that path is baked in, so a later PATH change or Microsoft
  * Store update that re-points the `py`/`python` launcher cannot silently break
  * the hooks; candidates resolving to the non-spawnable WindowsApps stub are
- * skipped. Other platforms keep the bare command (e.g. `python3`).
+ * skipped. The path probe runs in isolated mode so the folder the installer
+ * runs from cannot slow or change it. Other platforms keep the bare command
+ * (e.g. `python3`).
  *
  * @returns {string|null} The interpreter command, or null when none is usable.
  */
@@ -561,7 +579,7 @@ export function detectPython() {
             const version = execSync(`${command} ${versionFlag}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: PYTHON_PROBE_TIMEOUT_MILLISECONDS }).trim();
             if (!version.includes('Python 3.')) continue;
             if (process.platform !== 'win32') return command;
-            const executablePath = execSync(`${command} -c "import sys; print(sys.executable)"`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: PYTHON_PROBE_TIMEOUT_MILLISECONDS }).trim();
+            const executablePath = execSync(pythonExecutableProbeCommand(command), { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], timeout: PYTHON_PROBE_TIMEOUT_MILLISECONDS }).trim();
             if (!executablePath || isWindowsStorePythonStub(executablePath)) continue;
             return interpreterCommandFromPath(executablePath);
         } catch { /* try next */ }
@@ -2688,6 +2706,7 @@ function executeInstallPlan(plan) {
             ...(plan.priorManifest.files || []),
             join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
             ...codexSolSettingSnapshotPaths(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
+            codexSolPromptPath(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
         ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });
@@ -2734,6 +2753,16 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     const groupLabel = selectedGroups ? `groups: ${selectedGroups.join(', ')}` : 'all';
     console.log(`\nInstalling ${PACKAGE_NAME} (${groupLabel})...\n`);
     console.log(`  Python: ${pythonCommand}`);
+    const shadowingGlobal = findShadowingGlobalInstall({
+        packageName: PACKAGE_NAME,
+        packageRoot: PACKAGE_ROOT,
+        packageVersion: PACKAGE_VERSION,
+    });
+    if (shadowingGlobal) {
+        const shadowAdvice = shadowingGlobalAdvice(PACKAGE_NAME, shadowingGlobal, PACKAGE_VERSION);
+        console.warn(`  Warning: ${shadowAdvice}`);
+        allActionNeededLines.push(shadowAdvice);
+    }
     mkdirSync(CLAUDE_HOME, { recursive: true });
     const publishedPointerPaths = publishManagedLookupPointers();
 
@@ -2993,6 +3022,9 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         console.log(cursorOutcome.warning
             ? `  DeepStack (cursor): ${cursorOutcome.status} — ${cursorOutcome.warning}`
             : `  DeepStack (cursor): ${cursorOutcome.status}`);
+        if (cursorOutcome.status === 'failed') {
+            allActionNeededLines.push(`DeepStack (cursor): failed — ${cursorOutcome.warning}`);
+        }
     }
     const allRepositoryPluginSpecs = [
         USAGE_WRAPUP_PLUGIN_SPEC,
@@ -3025,9 +3057,14 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
         );
         if (deepenGuidancePath) allCodexGuidancePaths.push(deepenGuidancePath);
+        const solPromptPath = installCodexSolPrompt(
+            INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+            join(PACKAGE_ROOT, SOL_PROMPT_DIRECTORY_NAME, SOL_PROMPT_FILE_NAME),
+        );
+        if (solPromptPath) allCodexGuidancePaths.push(solPromptPath);
         const solSettingPath = writeCodexSolSetting(
             INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
-            join(CLAUDE_HOME, SOL_PROMPT_DIRECTORY_NAME, SOL_PROMPT_FILE_NAME),
+            codexSolPromptPath(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
         );
         if (solSettingPath) {
             allCodexGuidancePaths.push(solSettingPath);
@@ -3245,6 +3282,7 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
         console.log(`  hooks: ${summary.hookFiles.created + summary.hookFiles.updated} files, ${summary.hookGroups} groups in settings.json`);
     }
     console.log(`  python: ${pythonCommand}\n`);
+    printActionNeeded();
 }
 
 function normalizePathForComparison(rawPath) {
@@ -3491,6 +3529,7 @@ function uninstall() {
             ...plan.removableFiles,
             join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
             ...codexSolSettingSnapshotPaths(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
+            codexSolPromptPath(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
         ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });

package/bin/install.test.mjs

@@ -3633,3 +3633,57 @@ test('a full install clears a retired session-continuity registration from every
         );
     }
 });
+
+function installWithGlobalPrefix(context, globalPrefix) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-action-needed-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    return spawnSync(process.execPath, [join(dirname(fileURLToPath(import.meta.url)), 'install.mjs')], {
+        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,
+            APPDATA: join(homeDirectory, 'AppData', 'Roaming'),
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            TEMP: homeDirectory,
+            TMP: homeDirectory,
+            npm_config_prefix: undefined,
+            npm_config_global_prefix: globalPrefix ?? join(homeDirectory, 'no-global-prefix'),
+        },
+    });
+}
+
+test('install ends with an Action needed block naming an older global copy that shadows npx', (context) => {
+    const globalPrefix = mkdtempSync(join(tmpdir(), 'cde-global-prefix-'));
+    context.after(() => rmSync(globalPrefix, { recursive: true, force: true }));
+    const globalPackage = process.platform === 'win32'
+        ? join(globalPrefix, 'node_modules', 'claude-dev-env')
+        : join(globalPrefix, 'lib', 'node_modules', 'claude-dev-env');
+    mkdirSync(globalPackage, { recursive: true });
+    writeFileSync(join(globalPackage, 'package.json'), JSON.stringify({ name: 'claude-dev-env', version: '0.0.1' }));
+
+    const result = installWithGlobalPrefix(context, globalPrefix);
+
+    assert.equal(result.status, 0, result.stderr);
+    const actionIndex = result.stderr.lastIndexOf('Action needed (1):');
+    assert.ok(actionIndex >= 0, result.stderr);
+    assert.match(result.stderr.slice(actionIndex), /claude-dev-env 0\.0\.1/);
+    assert.match(result.stderr.slice(actionIndex), /npm uninstall -g claude-dev-env/);
+});
+
+test('install prints no Action needed block when every side step finished', (context) => {
+    const result = installWithGlobalPrefix(context, null);
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stderr.includes('Action needed'), false, result.stderr);
+});

package/bin/python-probe.mjs

@@ -0,0 +1,20 @@
+/**
+ * Command line for the probe that asks a Python candidate for its absolute
+ * interpreter path.
+ *
+ * `python -c` puts the current directory first on `sys.path`, and Python
+ * lists that whole directory the first time it imports a module from disk.
+ * When the installer runs from a large folder, such as a temp folder with
+ * hundreds of thousands of entries, that listing can outlast the probe
+ * timeout, so every candidate fails and the install stops with "No usable
+ * Python 3 found". A module in that folder with a standard library name is
+ * imported in place of the real one. `-I` (isolated mode, Python 3.4+) keeps
+ * the current directory off `sys.path`, so the probe gives the same answer
+ * from any folder.
+ *
+ * @param {string} candidateCommand A Python launcher command, such as `py -3`.
+ * @returns {string} The shell command that prints the interpreter path.
+ */
+export function pythonExecutableProbeCommand(candidateCommand) {
+    return `${candidateCommand} -I -c "import sys; print(sys.executable)"`;
+}

package/bin/python-probe.test.mjs

@@ -0,0 +1,37 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execSync } from 'node:child_process';
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { detectPython } from './install.mjs';
+import { pythonExecutableProbeCommand } from './python-probe.mjs';
+
+const SHADOWED_STANDARD_LIBRARY_MODULES = ['linecache.py', 'encodings.py', 'site.py', 'os.py'];
+
+test('the interpreter path probe ignores modules in the current directory', () => {
+    const candidateCommand = detectPython();
+    assert.ok(candidateCommand, 'a Python 3 interpreter is needed for this test');
+    const shadowDirectory = mkdtempSync(join(tmpdir(), 'cde-python-probe-'));
+    try {
+        for (const moduleFileName of SHADOWED_STANDARD_LIBRARY_MODULES) {
+            writeFileSync(join(shadowDirectory, moduleFileName), 'raise SystemExit("shadow module imported")\n');
+        }
+        const printedPath = execSync(pythonExecutableProbeCommand(candidateCommand), {
+            cwd: shadowDirectory,
+            encoding: 'utf8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        assert.ok(printedPath.length > 0);
+        assert.doesNotMatch(printedPath, /shadow module imported/);
+    } finally {
+        rmSync(shadowDirectory, { recursive: true, force: true });
+    }
+});
+
+test('the interpreter path probe runs Python in isolated mode', () => {
+    assert.equal(
+        pythonExecutableProbeCommand('py -3'),
+        'py -3 -I -c "import sys; print(sys.executable)"',
+    );
+});

package/docs/agents-guidance/asks.md

@@ -40,6 +40,7 @@ What has been seen to work, in an interactive `cursor-agent` session (version 20
 - The `sessionStart` entry runs, and the session can quote the Asks line. Without it, the session cannot.
 - The `stop` entry runs at the end of each turn. With an open todo left, the gate sent one follow-up, and the agent closed the turn with a `Blocked:` line. Without the gate, the turn ended at "Done." with the todo still open.
 - A turn cancelled with Esc sends `stop` with status `aborted`, then `error`. The gate stays silent for both.
+- On Windows, each hook command runs in PowerShell: Cursor writes it into a temporary `.ps1` script and starts `pwsh -NonInteractive -File` on it. A command that starts with a quote gets the `&` call operator first, so a quoted Python path with a space runs. A probe from `C:/.../py space/venv/Scripts/python.exe` ran with both a bare and a quoted script path. The Cursor editor (3.24.12) has the same `&` rule in its hook runner.
 
 Limits:
 

package/docs/codex-accounts.md

@@ -133,7 +133,10 @@ Once installed, that is `~/.claude/scripts/account_broker.py`.
 
 The installer writes one top-level line into `~/.codex/config.toml`, under a
 `# claude-dev-env trimmed Sol prompt` marker. The line points
-`model_instructions_file` at `~/.claude/system-prompts/codex-sol.md`. The file
+`model_instructions_file` at `~/.codex/codex-sol.md`, a copy of the package's
+`system-prompts/codex-sol.md`. The copy sits beside `config.toml`, so pruning
+the managed files under `~/.claude`, which an older package version does on
+`--update`, cannot leave Codex pointing at a missing file. The file
 is Codex's default `gpt-6.1-sol` prompt with the lines that conflict with the
 package rules rewritten. The line names no model, so every Codex run uses the
 file, whichever model it selects. `sync` links `config.toml` into every account

package/docs/decisions/deepstack-gate.md

@@ -14,15 +14,19 @@ The filled four-answer stub printed `decision` `deepen`. The rewritten prompt ca
 
 | Reason | When |
 |---|---|
-| `restates-four-questions` | The rewrite contains every canonical question stem. The paste path is this case. |
+| `restates-four-questions` | The rewrite contains every canonical question stem. The old paste path was this case. |
 | `missing-role-lines` | `SCOPE (role):`, `EXAMPLES (illustration only):`, or `ZOOM-IN BLOCKER:` is missing or blank. |
 | `example-noun-in-scope` | The scope line contains an example noun and `ZOOM-IN BLOCKER:` is `none`. |
 | `dropped-hard-constraint` | A bullet under `HARD CONSTRAINTS` in the task is absent as its own line in the rewrite. |
 
 Json mode prints `{"decision": "refuse", "reason": "..."}`. Rewrite mode and the command-hook path print nothing, so the prompt-submit mod leaves the submitted text in place.
 
+## The default rewrite
+
+With no rewrite stub and no `CDE_DEEPEN_COMMAND`, `hooks/session/deepen_default_rewrite.py` builds the rewrite. It takes the scope from the task's own sentences, moves clauses the task marks as examples (`for example`, `for instance`, `e.g.`, `such as`) to the examples line, clips a scope over 240 characters with a pointer to the full task, copies the task with its hard constraints, and ends with one order to do the job. When the scope still names an example, the blocker line asks the worker to confirm before narrowing to it. The gate checks this rewrite like any other, so a first task deepens on every host with nothing configured.
+
 ## Proof shape
 
-Run the hook on stdin with `CDE_DEEPEN_OUTPUT=json`. The paste path refuses. A role rewrite that leaves the example noun out deepens. Removing `refusal_reason` from `decide_first_prompt` lets the paste path deepen again, and `test_should_refuse_the_paste_path_as_the_known_bad` fails. The wrong twin puts the example noun in the scope line with `ZOOM-IN BLOCKER: none` and is refused.
+Run the hook on stdin with `CDE_DEEPEN_OUTPUT=json`. A stub that pastes the four question stems refuses, and the default rewrite deepens. A role rewrite that leaves the example noun out deepens. Removing `refusal_reason` from `decide_first_prompt` lets the paste path deepen again, and `test_should_refuse_the_paste_path_as_the_known_bad` fails. The wrong twin puts the example noun in the scope line with `ZOOM-IN BLOCKER: none` and is refused.
 
 `hooks/session/grade_deepstack_replay.py` scores a fixture whose task names one failure as an example. It calls `refusal_reason` and does not rewrite.

package/hooks/features/session-context.md

@@ -18,6 +18,7 @@ This family injects reminders and task guidance when an agent starts, resumes, s
 - `session/skill_loaded_reminder.py` runs on `PreToolUse` matcher `Agent|Task` at `10` seconds, `UserPromptSubmit` matcher empty at `10` seconds, `SessionStart` matcher `compact` at `10` seconds, and `SubagentStart` matcher `workflow-subagent` at `10` seconds in `hooks.json`.
 - `session/task_tool_prompt.py`, `session/working_style_prompt.py`, `session/advisor_rules_prompt.py`, and `session/orchestrator_auto_starter.py` run on `SessionStart`, matcher empty, timeout `10` seconds each in `hooks.json`.
 - `session/deepen_first_prompt.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds in `hooks.json`.
+- In Cursor, `session/deepen_first_prompt.py` also runs on `beforeSubmitPrompt`. Cursor passes that event name to the `UserPromptSubmit` copy it imports from the Claude Code settings too. When both copies run, `session/deepen_turn_marker.py` creates the turn marker only when it does not exist yet, so one copy injects. A later prompt skips when either the transcript marker or the session marker exists, or when the transcript already has a user line in Claude Code's or Cursor's shape.
 - `session/artifact_template_pointer.py` runs on `PreToolUse` matcher `Artifact|Skill` at `10` seconds in `hooks.json`. It speaks only on an `Artifact` call with action `quickstart` or a `Skill` call that loads `artifact-design`.
 - `advisory/auto_mode_denial_quick_fix.py` runs on `PermissionDenied`, matcher `*`, timeout `10` seconds in `hooks.json`.
 
@@ -32,7 +33,7 @@ Preconditions:
 - **Working style.** Input is a SessionStart event. Run `python -m pytest packages/claude-dev-env/hooks/session/test_working_style_prompt.py -q`. The adjacent test observes the fixed context text.
 - **Advisor guidance.** Input is SessionStart with `advisorModel` set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_advisor_rules_prompt.py -q`. The adjacent test observes guidance only when the advisor setting is enabled.
 - **Orchestrator start.** Input is SessionStart with its opt-in flag set. Run `python -m pytest packages/claude-dev-env/hooks/session/test_orchestrator_auto_starter.py -q`. The adjacent test observes an orchestrator directive.
-- **First-task deepen.** Input is a first UserPromptSubmit task. Run `python -m pytest packages/claude-dev-env/hooks/session/test_deepen_first_prompt.py -q`. The adjacent test observes a skip table, a refusal of the paste path, and a rewrite that carries the SCOPE, EXAMPLES, and ZOOM-IN BLOCKER lines.
+- **First-task deepen.** Input is a first UserPromptSubmit task. Run `python -m pytest packages/claude-dev-env/hooks/session/test_deepen_first_prompt.py -q`. The adjacent test observes a skip table, a refusal of the paste path, a rewrite that carries the SCOPE, EXAMPLES, and ZOOM-IN BLOCKER lines, and one injection when two copies see the same Cursor prompt. `python -m pytest packages/claude-dev-env/hooks/session/test_deepen_turn_marker.py -q` observes that only the first marker claim wins. With nothing configured, `deepen_default_rewrite.py` builds that role-shaped rewrite, and `test_deepen_default_rewrite.py` checks the gate accepts it.
 - **Artifact template pointer.** Input is an `Artifact` quickstart call. Run `python -m pytest packages/claude-dev-env/hooks/session/test_artifact_template_pointer.py -q`. The adjacent test observes the status flowchart path first, the html-plan path ahead of the template path in `additionalContext`, and silence on a publish call or another skill.
 - **Denial quick fix.** Input is a `PermissionDenied` event with a bracketed rule label and a classifier verdict. Run `python -m pytest packages/claude-dev-env/hooks/advisory/test_auto_mode_denial_quick_fix.py -q`. The adjacent test observes the named rule, the allow entry, and the PowerShell block; a denial with no verdict gets a note and no block.
 

package/hooks/hooks_constants/deepen_default_rewrite_constants.py

@@ -0,0 +1,39 @@
+"""Named values for the role-shaped default rewrite of a first task."""
+
+from __future__ import annotations
+
+__all__ = [
+    "ALL_EXAMPLE_SENTENCE_MARKERS",
+    "DEFAULT_BLOCKER_TEMPLATE",
+    "DEFAULT_CLOSING_LINE",
+    "DEFAULT_SCOPE_MAX_CHARACTERS",
+    "DEFAULT_TASK_HEADING",
+    "ALL_EXAMPLE_END_MARKERS",
+    "EXAMPLE_LEAD_PUNCTUATION",
+    "EXAMPLE_LIST_SEPARATOR",
+    "EXAMPLE_MARKER_ALTERNATION_SEPARATOR",
+    "EXAMPLE_MARKER_PATTERN_TEMPLATE",
+    "SCOPE_CLIPPED_SUFFIX",
+    "SENTENCE_BREAK_PATTERN",
+    "WORD_SEPARATOR",
+]
+
+ALL_EXAMPLE_SENTENCE_MARKERS: tuple[str, ...] = ("for example", "for instance", "e.g.", "such as")
+EXAMPLE_LEAD_PUNCTUATION: str = " ,:;-"
+EXAMPLE_MARKER_ALTERNATION_SEPARATOR: str = "|"
+EXAMPLE_MARKER_PATTERN_TEMPLATE: str = r"(?<!\w)(?:{alternatives})(?!\w)"
+EXAMPLE_LIST_SEPARATOR: str = "; "
+WORD_SEPARATOR: str = " "
+ALL_EXAMPLE_END_MARKERS: tuple[str, ...] = (", and ", ", but ", ", then ", ", so ", ";", ")")
+SENTENCE_BREAK_PATTERN: str = r"(?<=[.!?])\s+(?=[A-Z0-9\"'`(\[])"
+DEFAULT_SCOPE_MAX_CHARACTERS: int = 240
+SCOPE_CLIPPED_SUFFIX: str = "(the rest is in the task below)"
+DEFAULT_TASK_HEADING: str = "Task as given:"
+DEFAULT_BLOCKER_TEMPLATE: str = (
+    "the scope names something the task also gives as an example ({examples}); "
+    "confirm the job is only that case before narrowing to it"
+)
+DEFAULT_CLOSING_LINE: str = (
+    "Work the whole scope as a leading practitioner in this field would, "
+    "keep every hard constraint, and then do exactly that job."
+)

package/hooks/hooks_constants/deepen_first_prompt_constants.py

@@ -45,6 +45,9 @@ __all__ = [
     "DEEPEN_SLASH_COMMAND",
     "DEEPEN_TIMEOUT_SECONDS",
     "DEEPEN_TURN_MARKER_SUFFIX",
+    "DEEPEN_SESSION_MARKER_PREFIX",
+    "ALL_FIRST_PROMPT_EVENT_NAMES",
+    "CURSOR_BEFORE_SUBMIT_PROMPT_EVENT_NAME",
     "HOOK_EVENT_NAME_KEY",
     "HOOK_SPECIFIC_OUTPUT_KEY",
     "JSONL_ROLE_KEY",
@@ -66,10 +69,15 @@ DEEPEN_MARKER: str = "CDE_DEEPEN:v1"
 DEEPEN_AGENT_MARKER: str = "CDE_DEEPEN_AGENT"
 DEEPEN_SLASH_COMMAND: str = "/deepen"
 DEEPEN_TURN_MARKER_SUFFIX: str = ".cde-deepen-turn1"
+DEEPEN_SESSION_MARKER_PREFIX: str = "cde-deepen-"
 DEEPEN_TIMEOUT_SECONDS: int = 10
 DEEPEN_COMMAND_TIMEOUT_MARGIN_SECONDS: int = 2
 DEEPEN_COMMAND_TIMEOUT_SECONDS: int = DEEPEN_TIMEOUT_SECONDS - DEEPEN_COMMAND_TIMEOUT_MARGIN_SECONDS
 USER_PROMPT_SUBMIT_EVENT_NAME: str = "UserPromptSubmit"
+CURSOR_BEFORE_SUBMIT_PROMPT_EVENT_NAME: str = "beforeSubmitPrompt"
+ALL_FIRST_PROMPT_EVENT_NAMES: frozenset[str] = frozenset(
+    {USER_PROMPT_SUBMIT_EVENT_NAME, CURSOR_BEFORE_SUBMIT_PROMPT_EVENT_NAME}
+)
 PROMPT_FIELD_NAME: str = "prompt"
 TRANSCRIPT_PATH_FIELD_NAME: str = "transcript_path"
 SESSION_ID_FIELD_NAME: str = "session_id"

package/hooks/session/deepen_default_rewrite.py

@@ -0,0 +1,128 @@
+"""Role-shaped default rewrite for a first task when no rewrite command is set.
+
+``refusal_reason`` in ``deepen_role_gate.py`` refuses a rewrite that pastes the
+four question stems back at the worker, and one without the SCOPE, EXAMPLES,
+and ZOOM-IN BLOCKER lines. The default rewrite is built to carry those lines,
+so a first task deepens on every host with nothing configured: the scope is
+the task's own sentences with the marked examples taken out, the examples are
+the parts the task marks as examples, and the blocker asks for confirmation
+when the scope names one of those examples.
+"""
+
+from __future__ import annotations
+
+import re
+
+from hooks_constants.deepen_default_rewrite_constants import (
+    ALL_EXAMPLE_END_MARKERS,
+    ALL_EXAMPLE_SENTENCE_MARKERS,
+    DEFAULT_BLOCKER_TEMPLATE,
+    DEFAULT_CLOSING_LINE,
+    DEFAULT_SCOPE_MAX_CHARACTERS,
+    DEFAULT_TASK_HEADING,
+    EXAMPLE_LEAD_PUNCTUATION,
+    EXAMPLE_LIST_SEPARATOR,
+    EXAMPLE_MARKER_ALTERNATION_SEPARATOR,
+    EXAMPLE_MARKER_PATTERN_TEMPLATE,
+    SCOPE_CLIPPED_SUFFIX,
+    SENTENCE_BREAK_PATTERN,
+    WORD_SEPARATOR,
+)
+from hooks_constants.deepen_first_prompt_constants import (
+    DEEPEN_MARKER,
+    HARD_CONSTRAINTS_LABEL,
+    REFUSAL_EXAMPLE_NOUN_IN_SCOPE,
+    ROLE_BLOCKER_LABEL,
+    ROLE_BLOCKER_NONE,
+    ROLE_EXAMPLES_LABEL,
+    ROLE_SCOPE_LABEL,
+)
+from deepen_role_gate import refusal_reason
+
+
+def _body_before_constraints(task_text: str) -> str:
+    all_body_lines: list[str] = []
+    for each_line in task_text.splitlines():
+        if each_line.strip().upper().startswith(HARD_CONSTRAINTS_LABEL):
+            break
+        all_body_lines.append(each_line)
+    return WORD_SEPARATOR.join(WORD_SEPARATOR.join(all_body_lines).split())
+
+
+def _sentences(body_text: str) -> list[str]:
+    return [each.strip() for each in re.split(SENTENCE_BREAK_PATTERN, body_text) if each.strip()]
+
+
+def _example_marker_pattern() -> re.Pattern[str]:
+    alternatives = EXAMPLE_MARKER_ALTERNATION_SEPARATOR.join(re.escape(each_marker) for each_marker in ALL_EXAMPLE_SENTENCE_MARKERS)
+    return re.compile(EXAMPLE_MARKER_PATTERN_TEMPLATE.format(alternatives=alternatives), re.IGNORECASE)
+
+
+def _split_example(sentence: str) -> tuple[str, list[str]]:
+    """Return the sentence without its marked examples, and the example texts.
+
+    A marker counts only as a whole phrase, so "for examples of" and "such
+    assumptions" stay in the scope. The earliest marker splits first, and the
+    text after the example is split again for later markers.
+    """
+    marker_match = _example_marker_pattern().search(sentence)
+    if marker_match is None:
+        return sentence, []
+    head = sentence[: marker_match.start()].rstrip(EXAMPLE_LEAD_PUNCTUATION + "(")
+    tail = sentence[marker_match.end() :].lstrip(EXAMPLE_LEAD_PUNCTUATION)
+    end_index = min(
+        (tail.find(each_end) for each_end in ALL_EXAMPLE_END_MARKERS if tail.find(each_end) >= 0),
+        default=len(tail),
+    )
+    example = tail[:end_index].rstrip(".!? ")
+    remainder_scope, all_remainder_examples = _split_example(
+        tail[end_index:].lstrip(EXAMPLE_LEAD_PUNCTUATION + ")")
+    )
+    all_examples = ([example] if example else []) + all_remainder_examples
+    scope_part = f"{head} {remainder_scope}".strip() if head else ""
+    return scope_part, all_examples
+
+
+def _clipped(text: str) -> str:
+    if len(text) <= DEFAULT_SCOPE_MAX_CHARACTERS:
+        return text
+    cut = text[:DEFAULT_SCOPE_MAX_CHARACTERS]
+    kept = cut[: cut.rfind(" ")] if " " in cut else cut
+    return f"{kept} {SCOPE_CLIPPED_SUFFIX}"
+
+
+def _scope_and_examples(task_text: str) -> tuple[str, str]:
+    all_splits = [_split_example(each) for each in _sentences(_body_before_constraints(task_text))]
+    all_examples = [each_example for _, all_sentence_examples in all_splits for each_example in all_sentence_examples]
+    all_scope_parts = [each_part for each_part, _ in all_splits if each_part]
+    scope_text = WORD_SEPARATOR.join(all_scope_parts) or task_text.strip()
+    examples_text = EXAMPLE_LIST_SEPARATOR.join(all_examples) if all_examples else ROLE_BLOCKER_NONE
+    return _clipped(scope_text), examples_text
+
+
+def _rewrite_with_blocker(scope: str, examples: str, blocker: str, task_text: str) -> str:
+    return (
+        f"{DEEPEN_MARKER}\n\n"
+        f"{ROLE_SCOPE_LABEL} {scope}\n"
+        f"{ROLE_EXAMPLES_LABEL} {examples}\n"
+        f"{ROLE_BLOCKER_LABEL} {blocker}\n\n"
+        f"{DEFAULT_TASK_HEADING}\n{task_text}\n\n"
+        f"{DEFAULT_CLOSING_LINE}"
+    )
+
+
+def role_default_rewrite(task_text: str) -> str:
+    """Return the default rewrite: role lines from the task, the task itself, and one closing order.
+
+    Args:
+        task_text: The first task with any leading /deepen removed.
+
+    Returns:
+        A rewrite that opens with the deepen marker and carries the three role lines.
+    """
+    scope, examples = _scope_and_examples(task_text)
+    rewrite = _rewrite_with_blocker(scope, examples, ROLE_BLOCKER_NONE, task_text)
+    if refusal_reason(task_text, rewrite) != REFUSAL_EXAMPLE_NOUN_IN_SCOPE:
+        return rewrite
+    blocker = DEFAULT_BLOCKER_TEMPLATE.format(examples=examples)
+    return _rewrite_with_blocker(scope, examples, blocker, task_text)