claude-dev-env 8.88.1 → 8.88.3

package/bin/profile-stop-gate.mjs

@@ -0,0 +1,193 @@
+import { existsSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH } from './install-constants.mjs';
+import {
+    discoverProfileSettingsPaths,
+    hostConfigurationIndent,
+    mergeProfileSettingsFile,
+} from './merge_profile_settings.mjs';
+import { normalizePathForComparison } from './resolve-install-root.mjs';
+
+const STOP_EVENT_NAME = 'Stop';
+const MANAGED_HOOKS_DIRECTORY_NAME = 'hooks';
+const SETTINGS_INDENT = '    ';
+
+function comparablePath(filesystemPath) {
+    try {
+        return normalizePathForComparison(realpathSync(filesystemPath));
+    } catch {
+        return normalizePathForComparison(filesystemPath);
+    }
+}
+
+function comparableCommand(command) {
+    const forwardSlashed = command.replace(/\\/g, '/');
+    return process.platform === 'win32' ? forwardSlashed.toLowerCase() : forwardSlashed;
+}
+
+/**
+ * Return the gate script's path under a Claude home, in the spelling hook commands compare by.
+ *
+ * @param {string} claudeHome
+ * @returns {string}
+ */
+export function gateScriptCommandFragment(claudeHome) {
+    return comparableCommand(join(claudeHome, MANAGED_HOOKS_DIRECTORY_NAME, ...CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH));
+}
+
+function isGateHook(eachHook, claudeHome) {
+    return typeof eachHook?.command === 'string'
+        && comparableCommand(eachHook.command).includes(gateScriptCommandFragment(claudeHome));
+}
+
+/**
+ * Find the open-tasks Stop gate hook the install wrote into the main settings.
+ *
+ * @param {string} mainSettingsPath
+ * @param {string} claudeHome
+ * @returns {Record<string, unknown>|null} A copy of the hook entry, or null when the main settings hold none.
+ */
+export function mainOpenTasksGateHook(mainSettingsPath, claudeHome) {
+    if (!existsSync(mainSettingsPath)) return null;
+    const settings = JSON.parse(readFileSync(mainSettingsPath, 'utf8'));
+    for (const eachGroup of settings?.hooks?.[STOP_EVENT_NAME] ?? []) {
+        for (const eachHook of eachGroup?.hooks ?? []) {
+            if (isGateHook(eachHook, claudeHome)) return structuredClone(eachHook);
+        }
+    }
+    return null;
+}
+
+/**
+ * List the settings.json of every other Claude profile on this machine.
+ *
+ * A profile whose settings.json links to the main settings already reads the
+ * main hooks, so it is left out, and so is the main file itself.
+ *
+ * @param {{ homeDirectory: string, environment?: Record<string, string|undefined>, mainSettingsPath: string }} options
+ * @returns {string[]}
+ */
+export function otherProfileSettingsPaths(options) {
+    const mainKey = comparablePath(options.mainSettingsPath);
+    const seenKeys = new Set([mainKey]);
+    const allOtherPaths = [];
+    for (const eachPath of discoverProfileSettingsPaths(options)) {
+        if (!existsSync(eachPath)) continue;
+        const pathKey = comparablePath(eachPath);
+        if (seenKeys.has(pathKey)) continue;
+        seenKeys.add(pathKey);
+        allOtherPaths.push(eachPath);
+    }
+    return allOtherPaths;
+}
+
+function stopHooks(settingsPath) {
+    const settingsText = readFileSync(settingsPath, 'utf8');
+    if (!settingsText.trim()) return [];
+    const settings = JSON.parse(settingsText);
+    const stopGroups = settings?.hooks?.[STOP_EVENT_NAME];
+    if (!Array.isArray(stopGroups)) return [];
+    return stopGroups.flatMap((eachGroup) => (Array.isArray(eachGroup?.hooks) ? eachGroup.hooks : []));
+}
+
+function profileGateCommands(settingsPath, claudeHome) {
+    return stopHooks(settingsPath)
+        .filter((eachHook) => isGateHook(eachHook, claudeHome))
+        .map((eachHook) => eachHook.command);
+}
+
+/**
+ * True when a profile's settings.json already runs a gate script from another Claude home.
+ *
+ * An install with CLAUDE_CONFIG_DIR set to the profile writes a gate entry
+ * for the profile's own copy of the script, and a second entry for the main
+ * home's copy would run the gate twice on every stop.
+ *
+ * @param {string} settingsPath
+ * @param {string} claudeHome
+ * @returns {boolean}
+ */
+export function profileRunsItsOwnGate(settingsPath, claudeHome) {
+    const scriptPathSuffix = `/${comparableCommand(join(MANAGED_HOOKS_DIRECTORY_NAME, ...CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH))}`;
+    return stopHooks(settingsPath).some((eachHook) => typeof eachHook?.command === 'string'
+        && comparableCommand(eachHook.command).includes(scriptPathSuffix)
+        && !isGateHook(eachHook, claudeHome));
+}
+
+/**
+ * Add the main settings' open-tasks Stop gate to every other profile's settings.json.
+ *
+ * A profile keeps its own settings and hooks. The merge adds the one gate
+ * entry, in the spelling the main settings use, only where it is missing;
+ * an entry left with an older interpreter spelling is replaced. The file as
+ * it was before either change is copied to a timestamped `.bak`. A profile
+ * that already runs its own copy of the gate script is left as it is.
+ *
+ * @param {{ mainSettingsPath: string, claudeHome: string, allProfileSettingsPaths: string[],
+ *   homeDirectory: string, now?: Date }} options
+ * @returns {{ settingsPath: string, additions: string[], backupPath: string|null }[]}
+ */
+export function addOpenTasksGateToProfiles(options) {
+    const gateHook = mainOpenTasksGateHook(options.mainSettingsPath, options.claudeHome);
+    if (!gateHook) return [];
+    const timestamp = (options.now ?? new Date()).toISOString().replace(/[:.]/g, '-');
+    const declaredSettings = [{ keyPath: ['hooks', STOP_EVENT_NAME], items: [{ hooks: [gateHook] }] }];
+    const allTargetPaths = options.allProfileSettingsPaths.filter(
+        (eachPath) => !profileRunsItsOwnGate(eachPath, options.claudeHome),
+    );
+    const allStalePaths = allTargetPaths.filter(
+        (eachPath) => profileGateCommands(eachPath, options.claudeHome)
+            .some((eachCommand) => eachCommand !== gateHook.command),
+    );
+    const originalTextByStalePath = new Map(allStalePaths.map((eachPath) => [eachPath, readFileSync(eachPath, 'utf8')]));
+    removeOpenTasksGateFromProfiles({ claudeHome: options.claudeHome, allProfileSettingsPaths: allStalePaths });
+    return allTargetPaths.map((eachPath) => {
+        const outcome = mergeProfileSettingsFile(eachPath, {
+            dryRun: false,
+            homeDirectory: options.homeDirectory,
+            timestamp,
+            declaredSettings,
+        });
+        if (outcome.backupPath && originalTextByStalePath.has(eachPath)) {
+            writeFileSync(outcome.backupPath, originalTextByStalePath.get(eachPath));
+        }
+        return outcome;
+    });
+}
+
+/**
+ * Remove the gate entry that points at the main Claude home from each listed profile settings path.
+ *
+ * Only a hook whose command runs the main home's gate script goes. A Stop
+ * group left empty goes too, and so does an emptied Stop list or hooks object.
+ *
+ * @param {{ claudeHome: string, allProfileSettingsPaths: string[] }} options
+ * @returns {string[]} The settings paths that changed.
+ */
+export function removeOpenTasksGateFromProfiles(options) {
+    const allChangedPaths = [];
+    for (const eachPath of options.allProfileSettingsPaths) {
+        const settingsText = readFileSync(eachPath, 'utf8');
+        if (!settingsText.trim()) continue;
+        const settings = JSON.parse(settingsText);
+        const stopGroups = settings?.hooks?.[STOP_EVENT_NAME];
+        if (!Array.isArray(stopGroups)) continue;
+        let removedCount = 0;
+        for (const eachGroup of stopGroups) {
+            if (!Array.isArray(eachGroup?.hooks)) continue;
+            const keptHooks = eachGroup.hooks.filter((eachHook) => !isGateHook(eachHook, options.claudeHome));
+            removedCount += eachGroup.hooks.length - keptHooks.length;
+            eachGroup.hooks = keptHooks;
+        }
+        if (removedCount === 0) continue;
+        settings.hooks[STOP_EVENT_NAME] = stopGroups.filter(
+            (eachGroup) => !Array.isArray(eachGroup?.hooks) || eachGroup.hooks.length > 0,
+        );
+        if (settings.hooks[STOP_EVENT_NAME].length === 0) delete settings.hooks[STOP_EVENT_NAME];
+        if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+        writeFileSync(eachPath, JSON.stringify(settings, null, hostConfigurationIndent(settingsText, SETTINGS_INDENT)) + '\n');
+        allChangedPaths.push(eachPath);
+    }
+    return allChangedPaths;
+}

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

@@ -0,0 +1,124 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+    addOpenTasksGateToProfiles,
+    otherProfileSettingsPaths,
+    removeOpenTasksGateFromProfiles,
+} from './profile-stop-gate.mjs';
+
+function makeHome(context) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-profile-gate-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    const claudeHome = join(homeDirectory, '.claude');
+    mkdirSync(claudeHome, { recursive: true });
+    const gateCommand = `python3 ${join(claudeHome, 'hooks', 'blocking', 'open_tasks_stop_gate.py').replace(/\\/g, '/')}`;
+    const mainSettingsPath = join(claudeHome, 'settings.json');
+    writeFileSync(mainSettingsPath, JSON.stringify({
+        hooks: { Stop: [{ hooks: [{ type: 'command', command: gateCommand, timeout: 10 }] }] },
+    }, null, 4));
+    return { homeDirectory, claudeHome, mainSettingsPath, gateCommand };
+}
+
+function writeProfile(homeDirectory, name, settings) {
+    const profileDirectory = join(homeDirectory, '.claude-profiles', name);
+    mkdirSync(profileDirectory, { recursive: true });
+    const settingsPath = join(profileDirectory, 'settings.json');
+    if (settings !== undefined) writeFileSync(settingsPath, JSON.stringify(settings, null, 4));
+    return settingsPath;
+}
+
+function stopCommands(settingsPath) {
+    const settings = JSON.parse(readFileSync(settingsPath, 'utf8'));
+    return (settings.hooks?.Stop ?? []).flatMap((eachGroup) => eachGroup.hooks.map((eachHook) => eachHook.command));
+}
+
+test('every profile with its own settings.json gets the main gate entry', (context) => {
+    const { homeDirectory, claudeHome, mainSettingsPath, gateCommand } = makeHome(context);
+    const ownHooksPath = writeProfile(homeDirectory, 'own-hooks', {
+        hooks: { Stop: [{ hooks: [{ type: 'command', command: 'python3 /opt/own/stop.py' }] }] },
+    });
+    const prefsOnlyPath = writeProfile(homeDirectory, 'prefs-only', { outputStyle: 'plain' });
+    writeProfile(homeDirectory, 'no-settings');
+
+    const allProfilePaths = otherProfileSettingsPaths({ homeDirectory, environment: {}, mainSettingsPath });
+    addOpenTasksGateToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: allProfilePaths, homeDirectory });
+
+    assert.deepEqual(allProfilePaths.sort(), [ownHooksPath, prefsOnlyPath].sort());
+    assert.deepEqual(stopCommands(ownHooksPath), ['python3 /opt/own/stop.py', gateCommand]);
+    assert.deepEqual(stopCommands(prefsOnlyPath), [gateCommand]);
+    assert.equal(JSON.parse(readFileSync(prefsOnlyPath, 'utf8')).outputStyle, 'plain');
+});
+
+test('a profile whose settings.json links to the main settings is left out', (context) => {
+    const { homeDirectory, mainSettingsPath } = makeHome(context);
+    const linkedPath = writeProfile(homeDirectory, 'linked');
+    try {
+        symlinkSync(mainSettingsPath, linkedPath, 'file');
+    } catch (error) {
+        if (error.code === 'EPERM') return context.skip('this account cannot create symlinks');
+        throw error;
+    }
+
+    assert.deepEqual(otherProfileSettingsPaths({ homeDirectory, environment: {}, mainSettingsPath }), []);
+});
+
+test('a second run adds nothing, and an older interpreter spelling is replaced', (context) => {
+    const { homeDirectory, claudeHome, mainSettingsPath, gateCommand } = makeHome(context);
+    const staleCommand = gateCommand.replace(/^python3/, '/usr/bin/python3.9');
+    const profilePath = writeProfile(homeDirectory, 'stale', {
+        hooks: { Stop: [{ hooks: [{ type: 'command', command: staleCommand }] }] },
+    });
+    const options = { mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory };
+
+    addOpenTasksGateToProfiles(options);
+    const secondOutcome = addOpenTasksGateToProfiles(options);
+
+    assert.deepEqual(stopCommands(profilePath), [gateCommand]);
+    assert.deepEqual(secondOutcome[0].additions, []);
+});
+
+test('replacing an older spelling backs up the file as it was before the replacement', (context) => {
+    const { homeDirectory, claudeHome, mainSettingsPath, gateCommand } = makeHome(context);
+    const staleCommand = gateCommand.replace(/^python3/, '/usr/bin/python3.9');
+    const profilePath = writeProfile(homeDirectory, 'stale', {
+        hooks: { Stop: [{ hooks: [{ type: 'command', command: staleCommand }] }] },
+    });
+    const originalText = readFileSync(profilePath, 'utf8');
+
+    const [outcome] = addOpenTasksGateToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
+
+    assert.equal(readFileSync(outcome.backupPath, 'utf8'), originalText);
+});
+
+test('removal takes out only the main gate entry and leaves the profile as it was', (context) => {
+    const { homeDirectory, claudeHome, mainSettingsPath } = makeHome(context);
+    const ownHooksPath = writeProfile(homeDirectory, 'own-hooks', {
+        hooks: { Stop: [{ hooks: [{ type: 'command', command: 'python3 /opt/own/stop.py' }] }] },
+    });
+    const prefsOnlyPath = writeProfile(homeDirectory, 'prefs-only', { outputStyle: 'plain' });
+    const allProfilePaths = [ownHooksPath, prefsOnlyPath];
+    addOpenTasksGateToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: allProfilePaths, homeDirectory });
+
+    const allChangedPaths = removeOpenTasksGateFromProfiles({ claudeHome, allProfileSettingsPaths: allProfilePaths });
+
+    assert.deepEqual(allChangedPaths, allProfilePaths);
+    assert.deepEqual(stopCommands(ownHooksPath), ['python3 /opt/own/stop.py']);
+    assert.deepEqual(JSON.parse(readFileSync(prefsOnlyPath, 'utf8')), { outputStyle: 'plain' });
+});
+
+test('a profile that already runs its own copy of the gate script gets no second entry', (context) => {
+    const { homeDirectory, claudeHome, mainSettingsPath } = makeHome(context);
+    const ownGateCommand = `python3 ${join(homeDirectory, '.claude-profiles', 'isolated', 'hooks', 'blocking', 'open_tasks_stop_gate.py').replace(/\\/g, '/')}`;
+    const profilePath = writeProfile(homeDirectory, 'isolated', {
+        hooks: { Stop: [{ hooks: [{ type: 'command', command: ownGateCommand }] }] },
+    });
+
+    const allOutcomes = addOpenTasksGateToProfiles({ mainSettingsPath, claudeHome, allProfileSettingsPaths: [profilePath], homeDirectory });
+
+    assert.deepEqual(allOutcomes, []);
+    assert.deepEqual(stopCommands(profilePath), [ownGateCommand]);
+});

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.
+- 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.
 - 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.
 
@@ -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,14 +133,26 @@ 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
 home, so every account gets the line.
 
+When `CODEX_HOME/config.toml` is the same file as `~/.codex/config.toml`, the
+copy goes in `~/.codex`. `sync` makes that file a symbolic link, or a hard link
+when the account cannot create symbolic links. Installing from an account home
+then names the shared copy in `~/.codex`, and deleting or uninstalling that
+account home leaves the other homes working. A `config.toml` that links
+anywhere else, such as a dotfiles folder, keeps the copy in `CODEX_HOME`.
+
 A `model_instructions_file` the user wrote at the top level keeps the config as
-it is. Uninstall removes only the package line.
+it is. Uninstall removes only the package line and the copy. Uninstalling from
+an account home that shares `~/.codex/config.toml` leaves both alone, because
+`~/.codex` still uses them.
 
 To see which prompt Codex uses, read the setting:
 

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: