claude-dev-env 8.72.2 → 8.73.0

package/.agents/skills/build-eval/SKILL.md

@@ -4,7 +4,8 @@ description: >-
   Evaluate skills with a bounded direct Codex review suite or `claude plugin eval`.
   Use labeled inputs and deterministic grading for output correctness; use a plugin
   wrapper and with/without-plugin comparisons for discovery and contribution.
-  Use when the user asks to eval or test a skill.
+  Use when the user asks to eval or test a skill, asks whether a context file is
+  thin enough, or asks to check the context budget.
 ---
 
 # Build eval
@@ -16,6 +17,7 @@ It includes labeled cases, executable witnesses, related-group holdouts, a bound
 grading. Start with its validation command and two-case smoke. Preserve the distinction
 between grader validation, stored replay, a fresh recipe run and a complete workflow run.
 Use the plugin process below when measuring skill discovery or with/without-plugin contribution.
+To check whether a context file is thin enough, follow [the context budget page](reference/context-budget.md).
 
 ## Contents
 
@@ -101,10 +103,4 @@ Otherwise work the steps in order.
 - `SKILL.md`. Wrapper layout, gotchas, and process.
 - `reference/graders-and-commands.md`. Prompt frontmatter, grader types, case set, eval commands,
   and the `claude -p` recipe for flag-gated features.
-
-```text
-build-eval/
-├── SKILL.md
-└── reference/
-    └── graders-and-commands.md
-```
+- `reference/context-budget.md`. The context budget command and the fix for each finding.

package/.agents/skills/build-eval/reference/context-budget.md

@@ -0,0 +1,49 @@
+# Context budget
+
+Use this page for "is this context file thin enough?" and "check the context budget".
+
+An entry file is a short map. Detail lives in reference files the agent opens on demand. The repository's `.claude/context-budget.json` names each kind of context file, its line limit, and whether the section rule applies. Its baseline lists the files and hooks that were over budget when the list was built. A listed file's `lines` is its recorded count when it is over its line limit, and `null` when it is listed only for its sections. A file under its limit may grow up to the limit. A file over its limit and a listed hook may only shrink.
+
+## Check one file
+
+Run from inside the repository whose policy applies:
+
+```text
+python packages/claude-dev-env/scripts/context_budget_check.py <path> [<path> ...]
+```
+
+Each file's committed `HEAD` version is its prior state, so the grown and ratchet checks work outside a pull request. The command prints `context-budget: OK (<n> checked)` and exits 0 when every file is within budget. Otherwise it prints one finding per line and exits 1.
+
+## Check the hooks
+
+```text
+python packages/claude-dev-env/scripts/context_budget_check.py --hooks
+```
+
+It runs each hook in the policy's `hooks` list and prints the characters each one injects, its limit, and its baseline.
+
+## Fix a finding
+
+| Finding | Fix |
+| --- | --- |
+| `section "<heading>" has <n> detail lines and no pointer` | Move the section body to `reference/<kebab-heading>.md` and leave a one-line link to it. |
+| `file has <n> lines (<kind> limit <limit>)` | Move detail sections to reference files and leave one-line links. |
+| `grew from <n> to <m> lines` | Move detail out until the file is back to its recorded count or fewer. |
+| `was already over its limit at <n> lines and may only shrink` | Move detail out until the file has its prior count or fewer. The write hook gives this in a repository with no policy file. |
+| `file is below its over-budget entry` | Set the entry to the numbers the message gives, `null` lines when the file is within its limit, or remove it. |
+| `the over-budget list may only shrink` | Restore the prior policy value and shrink the context instead. |
+| `hook "<name>" injects <n> characters` | Move the hook's text to a skill or reference file and inject a pointer. |
+
+## Rebuild the over-budget list
+
+A person never edits the baseline by hand. After a change shrinks listed files, rebuild it:
+
+```text
+python packages/claude-dev-env/scripts/context_budget_check.py --write-baseline
+```
+
+## Where it runs
+
+- The `context-budget` and `context-budget-policy` rules in `cde_lint` run in CI on every pull request.
+- The write hook `hooks/blocking/context_budget_blocker.py` denies a Write, Edit, MultiEdit, or apply_patch that takes a context file past its budget, in any repository the session edits. With no policy file, it holds a file over its limit to its prior line count.
+- `hooks/test_context_budget_hooks.py` holds each listed hook to its budget.

package/.agents/skills/orchestrator/reference/oversee-delegated-work.md

@@ -9,4 +9,5 @@ The `spawn_oversight_hook` adds this duty to every spawn, at every level of the
 - Before its output reaches the user, check it against the user's words and standards yourself.
 - Send the agent a correction when it misses, and check the corrected output the same way.
 - Give each piece of a multi-piece task its own reviewer or helper.
+- Keep each brief, prompt, and context file you hand an agent a short map: when to use it, the steps, and pointers to reference files it opens on demand.
 - Show the user you are involved: say what you checked and what you corrected.

package/.agents/skills/pr-lifecycle/SKILL.md

@@ -22,21 +22,14 @@ User-level rule: applies to **every** git repo that uses GitHub with `gh`. Small
 
 ### Pull request submission rules
 
-**Prove the change where it runs before you open the pull request.** The body carries a
-"Proof in practice" section with each command you ran and its quoted output. A hook denies
-a new pull request without one. Read `~/.claude/docs/rule-guides/proof-before-pull-request.md`
-before you plan the proof run. A `feat` pull request also needs an "Eval" section and a
-session that invoked `/claude-api build-eval`; read
-`~/.claude/docs/rule-guides/features-start-with-an-eval.md` before you build the feature.
+**Prove the change where it runs before opening a PR.** Read `~/.claude/docs/rule-guides/proof-before-pull-request.md` for the body and hook requirements. A `feat` PR also needs an "Eval" section and a session that invoked `/claude-api build-eval`; read `~/.claude/docs/rule-guides/features-start-with-an-eval.md` before you build the feature.
 
-**Open every pull request ready for review.** Pass `--draft` only when the owner asks
-for a draft.
+**Open PRs ready for review; use `--draft` when the owner requests it.**
 
 **A release bot's PR body is machine input. Leave it alone.** Release automation reads
 back the body of its own merged pull request to decide it owns that merge. Rewriting the
 body, or trimming its header or footer, makes the bot treat the merge as somebody else's
-work: it cuts no tag, the publish job skips, and it opens one more release pull request on
-the next run. The merge stays in the repository. No tag is cut and the package never publishes.
+work: it cuts no tag, skips publishing, and opens another release PR on the next run.
 
 Spot one by its head branch, which starts `release-please--branches--`, or by a body that
 opens with the bot's own marker line. The description rules in this file, the

package/bin/codex-trimmed-sol.mjs

@@ -0,0 +1,109 @@
+import { lstatSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const SOL_PROMPT_DIRECTORY_NAME = 'system-prompts';
+export const SOL_PROMPT_FILE_NAME = 'codex-sol.md';
+export const CODEX_CONFIG_FILE_NAME = 'config.toml';
+export const SOL_SETTING_MARKER = '# claude-dev-env trimmed Sol prompt. A claude-dev-env install rewrites the next line.';
+const INSTRUCTIONS_KEY_PATTERN = /^\s*model_instructions_file\s*=/;
+const TABLE_HEADER_PATTERN = /^\s*\[/;
+
+/**
+ * Return the two config.toml lines that point Codex at the trimmed prompt.
+ *
+ * `model_instructions_file` replaces the selected model's built-in prompt with
+ * the file it names, for every model a run selects. JSON string escaping is
+ * valid TOML basic-string escaping, so a Windows path keeps its backslashes.
+ *
+ * @param {string} instructionsPath Absolute path of the installed prompt file.
+ * @returns {string[]}
+ */
+export function solSettingLines(instructionsPath) {
+    return [SOL_SETTING_MARKER, `model_instructions_file = ${JSON.stringify(instructionsPath)}`];
+}
+
+function isPackageMarkerLine(eachLine) {
+    return eachLine.replace(/\r$/, '') === SOL_SETTING_MARKER;
+}
+
+function withoutPackageSetting(allLines) {
+    const allKeptLines = [];
+    for (let i = 0; i < allLines.length; i++) {
+        if (isPackageMarkerLine(allLines[i])) {
+            i++;
+            continue;
+        }
+        allKeptLines.push(allLines[i]);
+    }
+    return allKeptLines;
+}
+
+function hasUserInstructionsSetting(allLines) {
+    for (const eachLine of allLines) {
+        if (TABLE_HEADER_PATTERN.test(eachLine)) return false;
+        if (INSTRUCTIONS_KEY_PATTERN.test(eachLine)) return true;
+    }
+    return false;
+}
+
+function readCodexConfig(configPath) {
+    const configEntry = lstatSync(configPath, { throwIfNoEntry: false });
+    if (!configEntry) return { isReadable: true, currentText: null };
+    if (configEntry.isDirectory()) return { isReadable: false, currentText: null };
+    return { isReadable: true, currentText: readFileSync(configPath, 'utf8') };
+}
+
+export function codexSolSettingSnapshotPaths(codexHome) {
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const { isReadable, currentText } = readCodexConfig(configPath);
+    return isReadable && currentText !== null ? [configPath] : [];
+}
+
+/**
+ * Point CODEX_HOME/config.toml's `model_instructions_file` at the installed Sol prompt.
+ *
+ * The package line sits at the top of the file, before any table, so it is a
+ * top-level key. A top-level `model_instructions_file` the user wrote keeps
+ * the file as it is, and so does a directory at the config path.
+ *
+ * @param {string} codexHome
+ * @param {string} instructionsPath Absolute path of the installed prompt file.
+ * @returns {string|null} The config path when the file changed, and null otherwise.
+ */
+export function writeCodexSolSetting(codexHome, instructionsPath) {
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const { isReadable, currentText } = readCodexConfig(configPath);
+    if (!isReadable) return null;
+    const allUserLines = withoutPackageSetting((currentText ?? '').split('\n'));
+    if (hasUserInstructionsSetting(allUserLines)) return null;
+    const userText = allUserLines.join('\n');
+    const configText = [...solSettingLines(instructionsPath), userText === '' ? '' : userText].join('\n');
+    if (currentText === configText) return null;
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, configText, 'utf8');
+    return configPath;
+}
+
+/**
+ * Remove the package's `model_instructions_file` line from CODEX_HOME/config.toml.
+ *
+ * The rest of the file stays as the user wrote it. A file that held only the
+ * package line is removed.
+ *
+ * @param {string} codexHome
+ * @returns {string|null} The config path when it changed, or null when nothing was removed.
+ */
+export function removeCodexSolSetting(codexHome) {
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const { isReadable, currentText } = readCodexConfig(configPath);
+    if (!isReadable || currentText === null) return null;
+    const allLines = currentText.split('\n');
+    if (!allLines.some(isPackageMarkerLine)) return null;
+    const userText = withoutPackageSetting(allLines).join('\n');
+    if (userText.trim() === '') {
+        unlinkSync(configPath);
+    } else {
+        writeFileSync(configPath, userText, 'utf8');
+    }
+    return configPath;
+}

package/bin/codex-trimmed-sol.test.mjs

@@ -0,0 +1,226 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+    CODEX_CONFIG_FILE_NAME,
+    codexSolSettingSnapshotPaths,
+    removeCodexSolSetting,
+    solSettingLines,
+    writeCodexSolSetting,
+} from './codex-trimmed-sol.mjs';
+
+const packageDirectory = fileURLToPath(new URL('..', import.meta.url));
+const installerPath = join(packageDirectory, 'bin', 'install.mjs');
+const shippedPromptPath = join(packageDirectory, 'system-prompts', 'codex-sol.md');
+
+function makeScratchHome(context) {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cde-sol-setting-'));
+    context.after(() => rmSync(homeDirectory, { recursive: true, force: true }));
+    return homeDirectory;
+}
+
+function installInScratchHome(homeDirectory, argumentsList = [], environment = {}) {
+    return spawnSync(process.execPath, [installerPath, ...argumentsList], {
+        cwd: packageDirectory,
+        encoding: 'utf8',
+        env: {
+            ...process.env,
+            CLAUDE_CONFIG_DIR: undefined,
+            LLM_SETTINGS_PROFILES_ROOT: undefined,
+            CDE_INSTALL_PSTACK: '0',
+            CDE_INSTALL_USAGE_WRAPUP: '0',
+            CDE_INSTALL_SUBAGENT_MODELS: '0',
+            CLAUDE_DEV_ENV_INSTALL_FAULT: undefined,
+            HOME: homeDirectory,
+            USERPROFILE: homeDirectory,
+            CODEX_HOME: join(homeDirectory, '.codex'),
+            GIT_CONFIG_GLOBAL: join(homeDirectory, '.gitconfig'),
+            TEMP: homeDirectory,
+            TMP: homeDirectory,
+            ...environment,
+        },
+    });
+}
+
+function settingText(instructionsPath, userText = '') {
+    return [...solSettingLines(instructionsPath), userText].join('\n');
+}
+
+test('setting lines point model_instructions_file at the prompt and name no model', () => {
+    const allLines = solSettingLines('/home/user/.claude/system-prompts/codex-sol.md');
+    assert.ok(allLines.includes('model_instructions_file = "/home/user/.claude/system-prompts/codex-sol.md"'));
+    assert.equal(allLines.some((eachLine) => /^\s*model\s*=/.test(eachLine)), false);
+});
+
+test('setting lines escape a Windows path as a TOML basic string', () => {
+    assert.ok(solSettingLines('C:\\Users\\user\\.claude\\system-prompts\\codex-sol.md').includes(
+        'model_instructions_file = "C:\\\\Users\\\\user\\\\.claude\\\\system-prompts\\\\codex-sol.md"',
+    ));
+});
+
+test('writing twice changes the config once and keeps user settings below the line', (context) => {
+    const codexHome = join(makeScratchHome(context), '.codex');
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const userText = 'model = "gpt-6.1-sol"\n\n[features]\nweb_search = true\n';
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, userText);
+    assert.equal(writeCodexSolSetting(codexHome, '/prompt.md'), configPath);
+    assert.equal(writeCodexSolSetting(codexHome, '/prompt.md'), null);
+    assert.equal(readFileSync(configPath, 'utf8'), settingText('/prompt.md', userText));
+    assert.equal(writeCodexSolSetting(codexHome, '/moved/prompt.md'), configPath);
+    assert.equal(readFileSync(configPath, 'utf8'), settingText('/moved/prompt.md', userText));
+    assert.deepEqual(codexSolSettingSnapshotPaths(codexHome), [configPath]);
+    assert.equal(removeCodexSolSetting(codexHome), configPath);
+    assert.equal(readFileSync(configPath, 'utf8'), userText);
+});
+
+test('a config saved with CRLF line endings still has its package line rewritten and removed', (context) => {
+    const codexHome = join(makeScratchHome(context), '.codex');
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const userText = 'model = "gpt-6.1-sol"\r\n';
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, settingText('/prompt.md', userText).replace(/\n/g, '\r\n').replace(/\r\r/g, '\r'));
+    assert.equal(writeCodexSolSetting(codexHome, '/moved/prompt.md'), configPath);
+    assert.equal(readFileSync(configPath, 'utf8'), settingText('/moved/prompt.md', userText));
+    writeFileSync(configPath, readFileSync(configPath, 'utf8').replace(/\r?\n/g, '\r\n'));
+    assert.equal(removeCodexSolSetting(codexHome), configPath);
+    assert.equal(readFileSync(configPath, 'utf8'), userText);
+});
+
+test('a user-written top-level model_instructions_file is neither rewritten nor removed', (context) => {
+    const codexHome = join(makeScratchHome(context), '.codex');
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const userText = 'model_instructions_file = "/mine.md"\n';
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, userText);
+    assert.equal(writeCodexSolSetting(codexHome, '/prompt.md'), null);
+    assert.equal(removeCodexSolSetting(codexHome), null);
+    assert.equal(readFileSync(configPath, 'utf8'), userText);
+});
+
+test('a model_instructions_file inside a table does not block the top-level setting', (context) => {
+    const codexHome = join(makeScratchHome(context), '.codex');
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const userText = '[profiles.other]\nmodel_instructions_file = "/other.md"\n';
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, userText);
+    assert.equal(writeCodexSolSetting(codexHome, '/prompt.md'), configPath);
+    assert.equal(readFileSync(configPath, 'utf8'), settingText('/prompt.md', userText));
+});
+
+test('a directory at the config path is left alone', (context) => {
+    const codexHome = join(makeScratchHome(context), '.codex');
+    mkdirSync(join(codexHome, CODEX_CONFIG_FILE_NAME), { recursive: true });
+    assert.equal(writeCodexSolSetting(codexHome, '/prompt.md'), null);
+    assert.equal(removeCodexSolSetting(codexHome), null);
+    assert.deepEqual(codexSolSettingSnapshotPaths(codexHome), []);
+});
+
+test('a missing config needs no prior snapshot', (context) => {
+    assert.deepEqual(codexSolSettingSnapshotPaths(join(makeScratchHome(context), '.codex')), []);
+});
+
+test('full install points config.toml model_instructions_file at the installed trimmed prompt', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const configPath = join(homeDirectory, '.codex', CODEX_CONFIG_FILE_NAME);
+    const installedPromptPath = join(homeDirectory, '.claude', 'system-prompts', 'codex-sol.md');
+
+    const firstInstallation = installInScratchHome(homeDirectory);
+    assert.equal(firstInstallation.status, 0, firstInstallation.stdout + firstInstallation.stderr);
+    assert.equal(readFileSync(configPath, 'utf8'), settingText(installedPromptPath));
+    assert.equal(readFileSync(installedPromptPath, 'utf8'), readFileSync(shippedPromptPath, 'utf8'));
+
+    const secondInstallation = installInScratchHome(homeDirectory);
+    assert.equal(secondInstallation.status, 0, secondInstallation.stdout + secondInstallation.stderr);
+    assert.equal(secondInstallation.stdout.includes('Codex trimmed Sol prompt setting'), false);
+    assert.equal(readFileSync(configPath, 'utf8'), settingText(installedPromptPath));
+});
+
+test('uninstall removes the package line and keeps the user config', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const codexHome = join(homeDirectory, '.codex');
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const userText = 'approval_policy = "never"\n';
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, userText);
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+
+    const uninstallation = installInScratchHome(homeDirectory, ['--uninstall']);
+    assert.equal(uninstallation.status, 0, uninstallation.stdout + uninstallation.stderr);
+    assert.equal(readFileSync(configPath, 'utf8'), userText);
+});
+
+test('uninstall removes a config that held only the package line', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const configPath = join(homeDirectory, '.codex', CODEX_CONFIG_FILE_NAME);
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    const uninstallation = installInScratchHome(homeDirectory, ['--uninstall']);
+    assert.equal(uninstallation.status, 0, uninstallation.stdout + uninstallation.stderr);
+    assert.equal(existsSync(configPath), false);
+});
+
+test('failed uninstall restores the config with the package line', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const configPath = join(homeDirectory, '.codex', CODEX_CONFIG_FILE_NAME);
+    const installation = installInScratchHome(homeDirectory);
+    assert.equal(installation.status, 0, installation.stdout + installation.stderr);
+    const priorConfig = readFileSync(configPath, 'utf8');
+
+    const uninstallation = installInScratchHome(homeDirectory, ['--uninstall'], {
+        CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',
+    });
+    assert.notEqual(uninstallation.status, 0);
+    assert.match(uninstallation.stderr, /prior installation restored/);
+    assert.equal(readFileSync(configPath, 'utf8'), priorConfig);
+});
+
+test('failed install restores a user config shared by two homes', (context) => {
+    const firstHome = makeScratchHome(context);
+    const secondHome = makeScratchHome(context);
+    const codexHome = join(firstHome, '.codex');
+    const configPath = join(codexHome, CODEX_CONFIG_FILE_NAME);
+    const userText = 'approval_policy = "never"\n';
+    mkdirSync(codexHome, { recursive: true });
+    writeFileSync(configPath, userText);
+
+    const failedInstallation = installInScratchHome(secondHome, [], {
+        CODEX_HOME: codexHome,
+        CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',
+    });
+    assert.notEqual(failedInstallation.status, 0);
+    assert.match(failedInstallation.stderr, /prior installation restored/);
+    assert.ok(failedInstallation.stdout.includes('Codex trimmed Sol prompt setting'));
+    assert.equal(readFileSync(configPath, 'utf8'), userText);
+});
+
+test('failed install removes a newly created config', (context) => {
+    const homeDirectory = makeScratchHome(context);
+    const installation = installInScratchHome(homeDirectory, [], {
+        CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',
+    });
+    assert.notEqual(installation.status, 0);
+    assert.match(installation.stderr, /prior installation restored/);
+    assert.ok(!existsSync(join(homeDirectory, '.codex', CODEX_CONFIG_FILE_NAME)));
+});
+
+test('failed install leaves a directory at the config path unchanged', (context) => {
+    const firstHome = makeScratchHome(context);
+    const secondHome = makeScratchHome(context);
+    const codexHome = join(firstHome, '.codex');
+    const sentinelPath = join(codexHome, CODEX_CONFIG_FILE_NAME, 'keep.txt');
+    mkdirSync(join(codexHome, CODEX_CONFIG_FILE_NAME), { recursive: true });
+    writeFileSync(sentinelPath, 'keep\n');
+    const installation = installInScratchHome(secondHome, [], {
+        CODEX_HOME: codexHome,
+        CLAUDE_DEV_ENV_INSTALL_FAULT: 'after_file_staging',
+    });
+    assert.notEqual(installation.status, 0);
+    assert.match(installation.stderr, /prior installation restored/);
+    assert.equal(readFileSync(sentinelPath, 'utf8'), 'keep\n');
+});

package/bin/install.mjs

@@ -60,6 +60,13 @@ import {
     shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
+import {
+    codexSolSettingSnapshotPaths,
+    removeCodexSolSetting,
+    SOL_PROMPT_DIRECTORY_NAME,
+    SOL_PROMPT_FILE_NAME,
+    writeCodexSolSetting,
+} from './codex-trimmed-sol.mjs';
 import {
     removeCodexPackageGuidance,
     removeCodexQuestionGuidance,
@@ -2631,6 +2638,7 @@ function executeInstallPlan(plan) {
         priorManifestFiles: [
             ...(plan.priorManifest.files || []),
             join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
+            ...codexSolSettingSnapshotPaths(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
         ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });
@@ -2912,6 +2920,14 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
             readFileSync(join(PACKAGE_ROOT, 'rules', 'question-presentation.md'), 'utf8'),
         );
         if (questionGuidancePath) allCodexGuidancePaths.push(questionGuidancePath);
+        const solSettingPath = writeCodexSolSetting(
+            INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
+            join(CLAUDE_HOME, SOL_PROMPT_DIRECTORY_NAME, SOL_PROMPT_FILE_NAME),
+        );
+        if (solSettingPath) {
+            allCodexGuidancePaths.push(solSettingPath);
+            console.log(`  \u2713 ${solSettingPath} (Codex trimmed Sol prompt setting)`);
+        }
     }
     syncWrittenPaths([...allInstalledFiles, ...allCodexGuidancePaths, ...publishedPointerPaths]);
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
@@ -3272,6 +3288,7 @@ function executeUninstallPlan(plan, helpers = {}) {
     }
     removeCodexPackageGuidance(INSTALL_ROOT_RESOLUTION.codexHomeDirectory);
     removeCodexQuestionGuidance(INSTALL_ROOT_RESOLUTION.codexHomeDirectory);
+    removeCodexSolSetting(INSTALL_ROOT_RESOLUTION.codexHomeDirectory);
     throwIfFault(FAULT_PHASES.AFTER_FILE_STAGING);
 
     if (existsSync(plan.settingsPath)) {
@@ -3365,6 +3382,7 @@ function uninstall() {
         priorManifestFiles: [
             ...plan.removableFiles,
             join(INSTALL_ROOT_RESOLUTION.codexHomeDirectory, 'AGENTS.md'),
+            ...codexSolSettingSnapshotPaths(INSTALL_ROOT_RESOLUTION.codexHomeDirectory),
         ],
         journalParentDirectory: join(CLAUDE_HOME, TRANSACTION_JOURNAL_DIRECTORY_NAME),
     });

package/bin/install.question-presentation.test.mjs

@@ -51,7 +51,7 @@ test('full install with pstack disabled delivers one question policy to Claude a
     assert.equal(readFileSync(join(homeDirectory, '.claude', 'rules', 'question-presentation.md'), 'utf8'), policyText);
     assert.match(readFileSync(codexGuidancePath, 'utf8'), /<!-- claude-dev-env question presentation: start -->/);
     assert.ok(readFileSync(codexGuidancePath, 'utf8').includes(policyText));
-    assert.equal(readFileSync(codexHooksPath, 'utf8'), hooksConfiguration);
+    assert.ok(readFileSync(codexHooksPath, 'utf8').endsWith(hooksConfiguration));
     const manifestPath = join(homeDirectory, '.claude', '.claude-dev-env-manifest.json');
     assert.equal(JSON.parse(readFileSync(manifestPath, 'utf8')).files.includes(codexGuidancePath), false);
 });

package/docs/codex-accounts.md

@@ -127,3 +127,29 @@ Once installed, that is `~/.claude/scripts/account_broker.py`.
 |---|---|
 | `_shared/pr-loop/scripts/check_convergence.py` | Requires a Codex clean stamp on HEAD only on `normal`. `luna`, `wait`, or a failed broker skips the Codex gate |
 | `_shared/advisor/scripts/codex_astra_advisor.py` | Binds Astra only on `normal`, and runs Codex with `CODEX_HOME` set to `decision.home` |
+
+## Trimmed Sol prompt
+
+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
+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.
+
+A `model_instructions_file` the user wrote at the top level keeps the config as
+it is. Uninstall removes only the package line.
+
+To see which prompt Codex uses, read the setting:
+
+```
+Select-String -Path "$HOME\.codex\config.toml" -Pattern model_instructions_file
+```
+
+To run Codex on the trimmed prompt through the broker, run it as usual. `run`
+reads all of standard input before it starts Codex, so close it:
+
+```
+python ~/.claude/scripts/account_broker.py run --product codex --report <report.json> -- codex exec "<request>" < /dev/null
+```