claude-dev-env 8.88.1 → 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,7 @@ 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)), '..');
@@ -443,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);
@@ -2691,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),
     });
@@ -2737,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();
 
@@ -2996,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,
@@ -3028,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);
@@ -3248,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) {
@@ -3494,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/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

@@ -33,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, 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.
+- **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/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)

package/hooks/session/deepen_first_prompt.py

@@ -31,8 +31,6 @@ from hooks_constants.cloud_session import is_cloud_session
 from hooks_constants.deepen_first_prompt_constants import (
     ADDITIONAL_CONTEXT_KEY,
     ALL_FIRST_PROMPT_EVENT_NAMES,
-    ALL_FOUR_QUESTION_STEMS,
-    QUESTION_LINE_SEPARATOR,
     ALL_HELPER_REPORT_MARKERS,
     ALL_LOOP_PROMPT_PREFIXES,
     ALL_NONINTERACTIVE_ENV_TRUE_VALUES,
@@ -68,6 +66,7 @@ from hooks_constants.deepen_first_prompt_constants import (
 from hooks_constants.mod_handoff import is_mod_plugin_enabled
 from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
 from hooks_constants.subprocess_window import hidden_window_creation_flags
+from deepen_default_rewrite import role_default_rewrite
 from deepen_role_gate import refusal_reason
 from deepen_turn_marker import claim_turn_marker, turn_marker_exists
 
@@ -256,19 +255,8 @@ def _command_rewrite(task_text: str) -> str | None:
 
 
 def _default_rewrite(task_text: str) -> str:
-    """Return the paste path: the four question stems and an order to do the job."""
-    numbered_stems = QUESTION_LINE_SEPARATOR.join(
-        f"{each_index}. {each_stem}"
-        for each_index, each_stem in enumerate(ALL_FOUR_QUESTION_STEMS, start=1)
-    )
-    return (
-        f"{DEEPEN_MARKER}\n\n"
-        "Do this task as a leading practitioner in its field would.\n\n"
-        f"{task_text}\n\n"
-        "Cover four things the original prompt left out:\n"
-        f"{numbered_stems}\n"
-        "Then do exactly that job."
-    )
+    """Return the role-shaped default rewrite the gate accepts."""
+    return role_default_rewrite(task_text)
 
 
 def expand_first_task(prompt: str) -> str: