claude-dev-env 8.84.1 → 8.85.1

package/bin/codex-skill-load-block.mjs

@@ -3,9 +3,6 @@ import { dirname, join, resolve } from 'node:path';
 
 export const SKILL_LOAD_BLOCK_START = '<!-- claude-dev-env skill load: start -->';
 export const SKILL_LOAD_BLOCK_END = '<!-- claude-dev-env skill load: end -->';
-export const SKILL_LOAD_INSTRUCTION = 'Load the pstack:poteto-mode skill before your first tool call or reply: '
-    + 'open its SKILL.md from your skills list and follow it. This binds every Codex agent, '
-    + 'including a helper started with spawn_agent, whatever its task message says.';
 export const PACKAGE_GUIDANCE_BLOCK_START = '<!-- claude-dev-env package guidance: start -->';
 export const PACKAGE_GUIDANCE_BLOCK_END = '<!-- claude-dev-env package guidance: end -->';
 export const QUESTION_PRESENTATION_BLOCK_START = '<!-- claude-dev-env question presentation: start -->';
@@ -39,17 +36,24 @@ function withBlockReplaced(guidanceText, blockStart, blockEnd, block) {
 }
 
 /**
- * Return the Codex guidance text with the package's skill-load block in it.
+ * Return guidance text with every complete skill-load block removed.
  *
- * Codex starts a spawn_agent helper without running any hook, so the global
- * AGENTS.md is the one channel that reaches every helper. A block already in
- * the text is replaced where it stands; otherwise the block goes first.
+ * When a block is the start of the remaining text, one following blank line is
+ * removed with it. A start marker with no end marker stays.
  */
-export function withSkillLoadBlock(guidanceText) {
-    const block = managedBlock(SKILL_LOAD_BLOCK_START, SKILL_LOAD_INSTRUCTION, SKILL_LOAD_BLOCK_END);
-    const replacedText = withBlockReplaced(guidanceText, SKILL_LOAD_BLOCK_START, SKILL_LOAD_BLOCK_END, block);
-    if (replacedText !== null) return replacedText;
-    return guidanceText ? `${block}\n${guidanceText}` : block;
+export function withoutSkillLoadBlock(guidanceText) {
+    let remainingText = guidanceText;
+    let removedBlockCount = 0;
+    while (remainingText.includes(SKILL_LOAD_BLOCK_START)) {
+        const blockStartsAtTop = remainingText.startsWith(SKILL_LOAD_BLOCK_START);
+        const replacedText = withBlockReplaced(remainingText, SKILL_LOAD_BLOCK_START, SKILL_LOAD_BLOCK_END, '');
+        if (replacedText === null || replacedText === remainingText) break;
+        removedBlockCount += 1;
+        remainingText = blockStartsAtTop && replacedText.startsWith('\n')
+            ? replacedText.slice(1)
+            : replacedText;
+    }
+    return removedBlockCount === 0 ? guidanceText : remainingText;
 }
 
 function withPackageGuidanceBlock(guidanceText, packageGuidanceText) {
@@ -84,7 +88,7 @@ function writeCodexGuidanceFile(codexHome, allPackageGuidancePaths, transformGui
     const isPackageGuidanceLink = agentsEntry?.isSymbolicLink() ?? false;
     if (isPackageGuidanceLink && !linksToPackageGuidance(agentsPath, allPackageGuidancePaths)) return null;
     const currentText = agentsEntry && !isPackageGuidanceLink ? readFileSync(agentsPath, 'utf8') : '';
-    const updatedText = transformGuidance(currentText);
+    const updatedText = transformGuidance(withoutSkillLoadBlock(currentText));
     if (!isPackageGuidanceLink && updatedText === currentText) return null;
     mkdirSync(codexHome, { recursive: true });
     if (isPackageGuidanceLink) unlinkSync(agentsPath);
@@ -93,29 +97,24 @@ function writeCodexGuidanceFile(codexHome, allPackageGuidancePaths, transformGui
 }
 
 /**
- * Keep CODEX_HOME/AGENTS.md carrying the skill-load block and the package guidance.
- *
- * The skill-load block goes first, and the package-guidance block holds the
- * current guidance text. A symbolic link that points at the package guidance
- * (the shared agents-home copy, or the retired copy under the Claude home) is
- * replaced by a regular file holding both blocks, so Codex keeps both after
- * the package moves its guidance. A link to any other file is left alone.
+ * Remove a skill-load block and write package guidance into CODEX_HOME/AGENTS.md.
  *
- * Returns the file path when the file changed, and null otherwise.
+ * Link handling matches writeCodexPackageGuidance. Returns the file path when
+ * the file changed, and null otherwise.
  */
 export function writeCodexAgentsGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
-    return writeCodexGuidanceFile(
-        codexHome,
-        allPackageGuidancePaths,
-        currentText => withPackageGuidanceBlock(withSkillLoadBlock(currentText), packageGuidanceText),
-    );
+    return writeCodexPackageGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths);
 }
 
 /**
  * Keep CODEX_HOME/AGENTS.md carrying the package guidance, with no skill-load block.
  *
- * Links follow the same rule as writeCodexAgentsGuidance. Returns the file
- * path when the file changed, and null otherwise.
+ * An existing skill-load block is removed. A symbolic link that points at the
+ * package guidance, the shared agents-home copy or the retired copy under the
+ * Claude home, is replaced by a regular file. A link to any other file is left
+ * alone.
+ *
+ * Returns the file path when the file changed, and null otherwise.
  */
 export function writeCodexPackageGuidance(codexHome, packageGuidanceText, allPackageGuidancePaths) {
     return writeCodexGuidanceFile(

package/bin/codex-skill-load-block.test.mjs

@@ -10,11 +10,10 @@ import {
     QUESTION_PRESENTATION_BLOCK_START,
     SKILL_LOAD_BLOCK_END,
     SKILL_LOAD_BLOCK_START,
-    SKILL_LOAD_INSTRUCTION,
     removeCodexDeepenGuidance,
     removeCodexPackageGuidance,
     removeCodexQuestionGuidance,
-    withSkillLoadBlock,
+    withoutSkillLoadBlock,
     DEEPEN_GUIDANCE_BLOCK_END,
     DEEPEN_GUIDANCE_BLOCK_START,
     DEEPEN_GUIDANCE_TEXT,
@@ -24,7 +23,10 @@ import {
     writeCodexQuestionGuidance,
 } from './codex-skill-load-block.mjs';
 
-const EXPECTED_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n${SKILL_LOAD_BLOCK_END}\n`;
+const STALE_SKILL_LOAD_SENTENCE = 'Load the pstack:poteto-mode skill before your first tool call or reply: '
+    + 'open its SKILL.md from your skills list and follow it. This binds every Codex agent, '
+    + 'including a helper started with spawn_agent, whatever its task message says.';
+const STALE_SKILL_LOAD_BLOCK = `${SKILL_LOAD_BLOCK_START}\n${STALE_SKILL_LOAD_SENTENCE}\n${SKILL_LOAD_BLOCK_END}\n`;
 const PACKAGE_GUIDANCE = 'Status\n\nChanged / proof / blocked.\n';
 const QUESTION_POLICY = '# Present questions clearly\n\nAsk one question.\n';
 
@@ -52,34 +54,44 @@ function writeGuidance(homes) {
     return writeCodexAgentsGuidance(homes.codexHome, PACKAGE_GUIDANCE, homes.allPackageGuidancePaths);
 }
 
-test('the instruction names the skill and binds spawned helpers', () => {
-    assert.match(SKILL_LOAD_INSTRUCTION, /pstack:poteto-mode/);
-    assert.match(SKILL_LOAD_INSTRUCTION, /spawn_agent/);
+test('a complete skill-load block is removed and the lines around it stay', () => {
+    assert.equal(withoutSkillLoadBlock(`Intro\n${STALE_SKILL_LOAD_BLOCK}Outro\n`), 'Intro\nOutro\n');
+    assert.equal(withoutSkillLoadBlock(`${STALE_SKILL_LOAD_BLOCK}\nNotes\n`), 'Notes\n');
+    assert.equal(
+        withoutSkillLoadBlock(`${STALE_SKILL_LOAD_BLOCK}\n${STALE_SKILL_LOAD_BLOCK}\nNotes\n`),
+        'Notes\n',
+    );
+    assert.equal(
+        withoutSkillLoadBlock(`${SKILL_LOAD_BLOCK_START}\nHalf a block\n`),
+        `${SKILL_LOAD_BLOCK_START}\nHalf a block\n`,
+    );
 });
 
-test('a missing Codex guidance file is created holding the skill-load block and the package guidance', (context) => {
+test('a missing Codex guidance file is created holding the package guidance', (context) => {
     const homes = makeHomes(context);
 
     const writtenPath = writeGuidance(homes);
 
     assert.equal(writtenPath, homes.agentsPath);
-    assert.equal(
-        readFileSync(homes.agentsPath, 'utf8'),
-        `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
-    );
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.equal(rendered, guidanceBlock(PACKAGE_GUIDANCE));
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
+    assert.equal(rendered.includes(SKILL_LOAD_BLOCK_START), false);
 });
 
-test('existing guidance keeps every line between the skill-load block and the package guidance', (context) => {
+test('existing guidance keeps its lines and gains the package guidance', (context) => {
     const homes = makeHomes(context);
     mkdirSync(homes.codexHome);
     writeFileSync(homes.agentsPath, '# pstack model configuration\n\nbug-fix: gpt-6-astra\n');
 
     writeGuidance(homes);
 
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
     assert.equal(
-        readFileSync(homes.agentsPath, 'utf8'),
-        `${EXPECTED_BLOCK}\n# pstack model configuration\n\nbug-fix: gpt-6-astra\n\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
+        rendered,
+        `# pstack model configuration\n\nbug-fix: gpt-6-astra\n\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
     );
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
 });
 
 test('a repeat install leaves the file unchanged and reports no write', (context) => {
@@ -93,20 +105,43 @@ test('a repeat install leaves the file unchanged and reports no write', (context
     assert.equal(readFileSync(homes.agentsPath, 'utf8'), afterFirstInstall);
 });
 
-test('an outdated block is replaced in place and the text around it is kept', () => {
-    const outdated = `Intro\n${SKILL_LOAD_BLOCK_START}\nOld wording\n${SKILL_LOAD_BLOCK_END}\nOutro\n`;
+test('a stale skill-load sentence is removed and question and deepen blocks stay', (context) => {
+    const homes = makeHomes(context);
+    mkdirSync(homes.codexHome);
+    const questionBlock = `${QUESTION_PRESENTATION_BLOCK_START}\n${QUESTION_POLICY}${QUESTION_PRESENTATION_BLOCK_END}\n`;
+    const deepenBlock = `${DEEPEN_GUIDANCE_BLOCK_START}\n${DEEPEN_GUIDANCE_TEXT}\n${DEEPEN_GUIDANCE_BLOCK_END}\n`;
+    writeFileSync(
+        homes.agentsPath,
+        `${STALE_SKILL_LOAD_BLOCK}\n${guidanceBlock('Old guidance\n')}${questionBlock}${deepenBlock}`,
+    );
 
-    assert.equal(withSkillLoadBlock(outdated), `Intro\n${EXPECTED_BLOCK}Outro\n`);
+    writeGuidance(homes);
+
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.equal(rendered.includes(STALE_SKILL_LOAD_SENTENCE), false);
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
+    assert.equal(rendered.includes(SKILL_LOAD_BLOCK_START), false);
+    assert.ok(rendered.includes(guidanceBlock(PACKAGE_GUIDANCE)));
+    assert.ok(rendered.includes(questionBlock));
+    assert.ok(rendered.includes(deepenBlock));
 });
 
-test('a start marker with no end marker gets a fresh block and keeps the stray text', () => {
+test('a start marker with no end marker stays and no skill name is added', (context) => {
+    const homes = makeHomes(context);
     const broken = `${SKILL_LOAD_BLOCK_START}\nHalf a block\n`;
+    mkdirSync(homes.codexHome);
+    writeFileSync(homes.agentsPath, broken);
+
+    writeGuidance(homes);
 
-    assert.equal(withSkillLoadBlock(broken), `${EXPECTED_BLOCK}\n${broken}`);
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.ok(rendered.startsWith(broken));
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
+    assert.ok(rendered.includes(PACKAGE_GUIDANCE_BLOCK_START));
 });
 
 for (const linkName of ['retiredGuidancePath', 'sharedGuidancePath']) {
-    test(`a link to package guidance at ${linkName} becomes a file with both blocks`, (context) => {
+    test(`a link to package guidance at ${linkName} becomes a file with the package block`, (context) => {
         const homes = makeHomes(context);
         mkdirSync(homes.codexHome);
         symlinkSync(homes[linkName], homes.agentsPath);
@@ -115,24 +150,21 @@ for (const linkName of ['retiredGuidancePath', 'sharedGuidancePath']) {
 
         assert.equal(writtenPath, homes.agentsPath);
         assert.equal(lstatSync(homes.agentsPath).isSymbolicLink(), false);
-        assert.equal(
-            readFileSync(homes.agentsPath, 'utf8'),
-            `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
-        );
+        assert.equal(readFileSync(homes.agentsPath, 'utf8'), guidanceBlock(PACKAGE_GUIDANCE));
+        assert.equal(readFileSync(homes.agentsPath, 'utf8').includes('pstack:poteto-mode'), false);
     });
 }
 
-test('a converted file takes the new package guidance on the next install', (context) => {
+test('a converted file takes the new package guidance and drops a stale skill-load block', (context) => {
     const homes = makeHomes(context);
     mkdirSync(homes.codexHome);
-    writeFileSync(homes.agentsPath, `${EXPECTED_BLOCK}\n${guidanceBlock('Old guidance\n')}`);
+    writeFileSync(homes.agentsPath, `${STALE_SKILL_LOAD_BLOCK}\n${guidanceBlock('Old guidance\n')}`);
 
     writeGuidance(homes);
 
-    assert.equal(
-        readFileSync(homes.agentsPath, 'utf8'),
-        `${EXPECTED_BLOCK}\n${guidanceBlock(PACKAGE_GUIDANCE)}`,
-    );
+    const rendered = readFileSync(homes.agentsPath, 'utf8');
+    assert.equal(rendered, guidanceBlock(PACKAGE_GUIDANCE));
+    assert.equal(rendered.includes('pstack:poteto-mode'), false);
 });
 
 test('a link to a file the package does not own is left alone', (context) => {

package/bin/install.mjs

@@ -2927,13 +2927,13 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
                     allUserOwnedPreferencePaths.add(eachPath);
                 }
             }
-            const skillLoadGuidancePath = writeCodexAgentsGuidance(
+            const codexGuidancePath = writeCodexAgentsGuidance(
                 INSTALL_ROOT_RESOLUTION.codexHomeDirectory,
                 packageGuidanceText,
                 allPackageGuidancePaths,
             );
-            if (skillLoadGuidancePath) {
-                console.log(`  \u2713 ${skillLoadGuidancePath} (Codex skill-load line)`);
+            if (codexGuidancePath) {
+                console.log(`  \u2713 ${codexGuidancePath} (Codex package guidance)`);
             }
         }
         printPluginHostOutcomes([PSTACK_PLUGIN_SPEC], pstackPlugin);

package/bin/install.prompt-context.test.mjs

@@ -35,11 +35,12 @@ test('reinstall drops the retired style reminder and keeps one skill reminder ho
     mergeHooksIntoSettings(settings, hooksConfig, 'C:/Users/example/.claude', 'python');
 
     const userPromptHooks = settings.hooks.UserPromptSubmit.flatMap(eachGroup => eachGroup.hooks);
-    assert.equal(userPromptHooks.length, 4);
+    assert.equal(userPromptHooks.length, 5);
     assert.equal(userPromptHooks[0].command, userCommand);
     assert.match(userPromptHooks[1].command, /session\/skill_loaded_reminder\.py$/);
     assert.match(userPromptHooks[2].command, /session\/deepen_first_prompt\.py$/);
     assert.match(userPromptHooks[3].command, /lifecycle\/nested_project_hooks\.py$/);
+    assert.match(userPromptHooks[4].command, /blocking\/chat_reply_gate\.py$/);
     assert.ok(userPromptHooks.every(eachHook => !eachHook.command.includes('style_reminder_prompt')));
 
     const firstMerge = JSON.stringify(settings);

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

@@ -171,7 +171,7 @@ test('a selected Claude profile receives the source rule and its Codex guidance'
     assert.ok(readFileSync(join(profileDirectory, '.codex', 'AGENTS.md'), 'utf8').includes(readFileSync(policyPath, 'utf8')));
 });
 
-test('a successful pstack install retains its skill block and gains the question block', (context) => {
+test('a successful pstack install omits the retired skill block and gains the question block', (context) => {
     const homeDirectory = makeScratchHome(context);
     const commandPath = join(homeDirectory, process.platform === 'win32' ? 'codex.cmd' : 'codex');
     writeFileSync(
@@ -191,7 +191,7 @@ test('a successful pstack install retains its skill block and gains the question
 
     assert.equal(installation.status, 0, installation.stdout + installation.stderr);
     const guidanceText = readFileSync(join(homeDirectory, '.codex', 'AGENTS.md'), 'utf8');
-    assert.match(guidanceText, /<!-- claude-dev-env skill load: start -->/);
+    assert.doesNotMatch(guidanceText, /<!-- claude-dev-env skill load: start -->/);
     assert.match(guidanceText, /<!-- claude-dev-env question presentation: start -->/);
     assert.ok(guidanceText.includes(readFileSync(policyPath, 'utf8')));
 });
@@ -221,7 +221,7 @@ test('enabling pstack after a pstack-off install preserves question guidance', (
     assert.equal(secondInstallation.status, 0, secondInstallation.stdout + secondInstallation.stderr);
     const updatedGuidance = readFileSync(codexGuidancePath, 'utf8');
     assert.ok(updatedGuidance.includes(firstGuidance));
-    assert.match(updatedGuidance, /<!-- claude-dev-env skill load: start -->/);
+    assert.doesNotMatch(updatedGuidance, /<!-- claude-dev-env skill load: start -->/);
     assert.match(updatedGuidance, /^feature, refactoring: gpt-6-sol$/m);
     assert.match(readFileSync(join(homeDirectory, '.codex', 'pstack-models.md'), 'utf8'), /^session hook: on$/m);
 });

package/bin/install.test.mjs

@@ -57,12 +57,12 @@ import {
 } from './install.mjs';
 import { EVER_SHIPPED_SKILL_NAMES } from './ever-shipped-skills.mjs';
 import {
+    DEEPEN_GUIDANCE_BLOCK_START,
     PACKAGE_GUIDANCE_BLOCK_END,
     PACKAGE_GUIDANCE_BLOCK_START,
-    SKILL_LOAD_BLOCK_START,
-    SKILL_LOAD_INSTRUCTION,
     QUESTION_PRESENTATION_BLOCK_START,
-    withSkillLoadBlock,
+    SKILL_LOAD_BLOCK_END,
+    SKILL_LOAD_BLOCK_START,
 } from './codex-skill-load-block.mjs';
 
 
@@ -3124,6 +3124,17 @@ function pstackPluginSandbox(t) {
     };
 }
 
+const STALE_SKILL_LOAD_SENTENCE = 'Load the pstack:poteto-mode skill before your first tool call or reply: '
+    + 'open its SKILL.md from your skills list and follow it. This binds every Codex agent, '
+    + 'including a helper started with spawn_agent, whatever its task message says.';
+
+function assertOmitsSkillLoadSentence(codexGuidance) {
+    assert.equal(codexGuidance.includes(SKILL_LOAD_BLOCK_START), false);
+    assert.equal(codexGuidance.includes(SKILL_LOAD_BLOCK_END), false);
+    assert.equal(codexGuidance.includes('pstack:poteto-mode'), false);
+    assert.equal(codexGuidance.includes(STALE_SKILL_LOAD_SENTENCE), false);
+}
+
 test('a full install adds the pstack marketplace and plugin on both hosts', t => {
     const sandbox = pstackPluginSandbox(t);
 
@@ -3145,9 +3156,10 @@ test('a full install adds the pstack marketplace and plugin on both hosts', t =>
     const sheet = readFileSync(join(codexHome, 'pstack-models.md'), 'utf8');
     const agents = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
     assert.match(sheet, /^session hook: on$/m);
+    assert.match(agents, /^# pstack model configuration\n/);
     assert.match(agents, /^feature, refactoring: gpt-6-sol$/m);
     assert.doesNotMatch(agents, /^session hook:/m);
-    assert.ok(agents.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assertOmitsSkillLoadSentence(agents);
     assert.equal(existsSync(join(sandbox.homeDirectory, '.claude', 'pstack-models.md')), false);
     const manifestPath = join(sandbox.homeDirectory, '.claude', '.claude-dev-env-manifest.json');
     const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
@@ -3159,14 +3171,19 @@ test('a repeat install preserves Codex pstack configuration', t => {
     const sandbox = pstackPluginSandbox(t);
     const codexHome = join(sandbox.homeDirectory, '.codex');
     runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
-    writeFileSync(join(codexHome, 'AGENTS.md'), 'Custom Codex guidance\n');
+    writeFileSync(
+        join(codexHome, 'AGENTS.md'),
+        `${SKILL_LOAD_BLOCK_START}\n${STALE_SKILL_LOAD_SENTENCE}\n${SKILL_LOAD_BLOCK_END}\nCustom Codex guidance\n`,
+    );
     writeFileSync(join(codexHome, 'pstack-models.md'), 'session hook: off\n');
 
     runPstackInstaller(sandbox.homeDirectory, [], sandbox.environment);
 
     const codexGuidance = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
-    assert.ok(codexGuidance.startsWith(withSkillLoadBlock('Custom Codex guidance\n')));
+    assert.ok(codexGuidance.startsWith('Custom Codex guidance\n'));
+    assertOmitsSkillLoadSentence(codexGuidance);
     assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
+    assert.ok(codexGuidance.includes(DEEPEN_GUIDANCE_BLOCK_START));
     assert.equal(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), 'session hook: off\n');
 });
 
@@ -3185,7 +3202,7 @@ test('a Codex guidance link to the retired Claude copy becomes a file Codex can
     );
     assert.equal(lstatSync(codexAgentsPath).isSymbolicLink(), false);
     const codexGuidance = readFileSync(codexAgentsPath, 'utf8');
-    assert.ok(codexGuidance.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assertOmitsSkillLoadSentence(codexGuidance);
     assert.ok(codexGuidance.includes(packageGuidance));
 });
 
@@ -3248,8 +3265,9 @@ test('a fresh full install writes the package guidance into Codex AGENTS.md', t
 
     const codexGuidance = readFileSync(join(sandbox.homeDirectory, '.codex', 'AGENTS.md'), 'utf8');
     assertHoldsPackageGuidance(codexGuidance);
-    assert.ok(codexGuidance.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assertOmitsSkillLoadSentence(codexGuidance);
     assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
+    assert.ok(codexGuidance.includes(DEEPEN_GUIDANCE_BLOCK_START));
 });
 
 test('--no-pstack writes package and question guidance without the skill-load block', t => {
@@ -3329,9 +3347,10 @@ test('a pstack install after a --no-pstack install seeds the Codex model sheet',
     assert.match(readFileSync(join(codexHome, 'pstack-models.md'), 'utf8'), /^session hook: on$/m);
     const codexGuidance = readFileSync(join(codexHome, 'AGENTS.md'), 'utf8');
     assert.match(codexGuidance, /^feature, refactoring: gpt-6-sol$/m);
-    assert.ok(codexGuidance.startsWith(`${SKILL_LOAD_BLOCK_START}\n${SKILL_LOAD_INSTRUCTION}\n`));
+    assertOmitsSkillLoadSentence(codexGuidance);
     assertHoldsPackageGuidance(codexGuidance);
     assert.ok(codexGuidance.includes(QUESTION_PRESENTATION_BLOCK_START));
+    assert.ok(codexGuidance.includes(DEEPEN_GUIDANCE_BLOCK_START));
 });
 
 const USAGE_WRAPUP_CLAUDE_COMMANDS = Object.freeze([

package/hooks/blocking/chat_reply_gate.py

@@ -0,0 +1,246 @@
+#!/usr/bin/env python3
+"""Hook that shows the user one short chat reply per message.
+
+``reply_length_gate.py`` checks only the chat tools that post to Slack.
+A reply typed straight into the chat is no tool call, so this hook runs
+the same checks on it::
+
+    UserPromptSubmit                       -> additionalContext states the rules
+    MessageDisplay, batch before the last  -> hold the text, show nothing yet
+    MessageDisplay, last batch, passes     -> show the whole message
+    MessageDisplay, last batch, fails      -> show a draft from a small model that passes
+
+A Stop hook would see the reply only after it is on screen, so each block
+would add a second reply under the first. MessageDisplay changes the text
+before it renders. The transcript keeps the original, so the next
+UserPromptSubmit tells the agent the text the user saw.
+
+The draft comes from ``claude -p`` on DEFAULT_DRAFTER_MODEL with no setting
+sources and no tools. The draft must pass ``reply_violation``; after
+MAXIMUM_DRAFT_ATTEMPTS failed drafts, the original shows.
+
+The checks come from ``reply_length_gate.reply_violation``: at most
+MAXIMUM_SENTENCE_COUNT sentences of at most MAXIMUM_WORDS_PER_SENTENCE
+words, no mid-sentence colon, no em dash, linked pull requests, a source
+for each causal claim, and no banned word.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import uuid
+from pathlib import Path
+
+hooks_root_directory = str(Path(__file__).resolve().parent.parent)
+if hooks_root_directory not in sys.path:
+    sys.path.insert(0, hooks_root_directory)
+blocking_directory = str(Path(__file__).resolve().parent)
+if blocking_directory not in sys.path:
+    sys.path.insert(0, blocking_directory)
+
+from reply_length_gate import reply_violation
+from hooks_constants.chat_reply_gate_constants import (
+    CLAUDE_SESSION_ID_ENV_VAR,
+    DEFAULT_DRAFTER_MODEL,
+    DELTA_KEY,
+    DISPLAY_CONTENT_KEY,
+    DRAFTER_GUARD_ENV_VAR,
+    DRAFTER_MODEL_ENV_VAR,
+    DRAFTER_REQUEST_TEMPLATE,
+    DRAFTER_ERROR_KEY,
+    DRAFTER_EXECUTABLE_NAME,
+    DRAFTER_RESULT_KEY,
+    DRAFTER_RULES,
+    DRAFTER_TIMEOUT_SECONDS,
+    FINAL_KEY,
+    HELD_TEXT_FILE_PREFIX,
+    HOOK_EVENT_NAME_INPUT_KEY,
+    MAXIMUM_DRAFT_ATTEMPTS,
+    MESSAGE_DISPLAY_EVENT_NAME,
+    MESSAGE_ID_KEY,
+    REPLY_LIMIT_REMINDER,
+    SESSION_END_EVENT_NAME,
+    SESSION_ID_KEY,
+    SHOWN_DRAFT_FILE_PREFIX,
+    SHOWN_DRAFT_PREFIX,
+    STATE_FILE_ENCODING,
+    STATE_FILE_SUFFIX,
+    USER_PROMPT_SUBMIT_EVENT_NAME,
+)
+from hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.hook_specific_output_keys import (
+    HOOK_EVENT_NAME_KEY,
+    HOOK_SPECIFIC_OUTPUT_KEY,
+)
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from hooks_constants.reply_length_gate_constants import (
+    ADDITIONAL_CONTEXT_KEY,
+    ALLOW_EXIT_CODE,
+)
+from hooks_constants.session_file_id import session_file_id
+
+
+def state_file_path(file_prefix: str, state_key: object) -> Path:
+    """Return the temp file that holds one message's held text or one session's shown draft."""
+    file_name = f"{file_prefix}{session_file_id(state_key)}{STATE_FILE_SUFFIX}"
+    return Path(tempfile.gettempdir()) / file_name
+
+
+def read_state_text(state_path: Path) -> str:
+    """Return the stored text, or an empty string when the file is absent or unreadable."""
+    try:
+        return state_path.read_text(encoding=STATE_FILE_ENCODING)
+    except OSError:
+        return ""
+
+
+def write_state_text(state_path: Path, state_text: str) -> None:
+    """Store the text; a failed write leaves the shown text unchanged."""
+    try:
+        state_path.write_text(state_text, encoding=STATE_FILE_ENCODING)
+    except OSError:
+        return
+
+
+def drafter_command() -> list[str]:
+    """Return the headless claude command that drafts with no settings and no tools."""
+    return [
+        shutil.which(DRAFTER_EXECUTABLE_NAME) or DRAFTER_EXECUTABLE_NAME,
+        "-p",
+        "--model",
+        os.environ.get(DRAFTER_MODEL_ENV_VAR, DEFAULT_DRAFTER_MODEL),
+        "--setting-sources",
+        "",
+        "--tools",
+        "",
+        "--no-session-persistence",
+        "--session-id",
+        str(uuid.uuid4()),
+        "--output-format",
+        "json",
+        "--system-prompt",
+        DRAFTER_RULES,
+    ]
+
+
+def drafter_environment() -> dict[str, str]:
+    """Return the drafter's environment, marked so this hook exits inside it."""
+    environment = dict(os.environ)
+    environment[DRAFTER_GUARD_ENV_VAR] = "1"
+    environment.pop(CLAUDE_SESSION_ID_ENV_VAR, None)
+    return environment
+
+
+def ask_drafter(reply_text: str, violation: str) -> str | None:
+    """Return one draft from the small model, or None when the call fails."""
+    try:
+        completed = subprocess.run(
+            drafter_command(),
+            input=DRAFTER_REQUEST_TEMPLATE.format(violation=violation, reply_text=reply_text),
+            capture_output=True,
+            text=True,
+            timeout=DRAFTER_TIMEOUT_SECONDS,
+            env=drafter_environment(),
+            check=False,
+        )
+        drafter_output = json.loads(completed.stdout)
+        draft_text = drafter_output.get(DRAFTER_RESULT_KEY)
+    except (OSError, subprocess.TimeoutExpired, json.JSONDecodeError, AttributeError):
+        return None
+    if drafter_output.get(DRAFTER_ERROR_KEY) is True:
+        return None
+    if not isinstance(draft_text, str) or not draft_text.strip():
+        return None
+    return draft_text.strip()
+
+
+def compliant_draft(reply_text: str, violation: str) -> str | None:
+    """Return a draft that passes ``reply_violation``, or None after MAXIMUM_DRAFT_ATTEMPTS."""
+    current_violation = violation
+    for _ in range(MAXIMUM_DRAFT_ATTEMPTS):
+        draft_text = ask_drafter(reply_text, current_violation)
+        if draft_text is None:
+            continue
+        draft_violation = reply_violation(draft_text, None, None)
+        if draft_violation is None:
+            return draft_text
+        current_violation = draft_violation
+    return None
+
+
+def shown_text(all_hook_input: dict[str, object]) -> str | None:
+    """Return the text to show for this batch, or None to show the batch as it is."""
+    message_id = all_hook_input.get(MESSAGE_ID_KEY)
+    if not isinstance(message_id, str) or not message_id:
+        return None
+    held_path = state_file_path(HELD_TEXT_FILE_PREFIX, message_id)
+    held_text = read_state_text(held_path)
+    message_text = held_text + str(all_hook_input.get(DELTA_KEY) or "")
+    if not all_hook_input.get(FINAL_KEY):
+        write_state_text(held_path, message_text)
+        return ""
+    held_path.unlink(missing_ok=True)
+    shown_draft_path = state_file_path(SHOWN_DRAFT_FILE_PREFIX, all_hook_input.get(SESSION_ID_KEY))
+    violation = reply_violation(message_text, None, None)
+    draft_text = None if violation is None else compliant_draft(message_text, violation)
+    if violation is None or draft_text is None:
+        shown_draft_path.unlink(missing_ok=True)
+        return message_text if held_text else None
+    write_state_text(shown_draft_path, draft_text)
+    log_hook_block(
+        Path(__file__).name,
+        MESSAGE_DISPLAY_EVENT_NAME,
+        violation,
+        offending_input_preview=message_text,
+    )
+    return draft_text
+
+
+def write_hook_output(event_name: str, output_key: str, output_text: str) -> None:
+    """Print one hookSpecificOutput field for the event."""
+    hook_event_output = {HOOK_EVENT_NAME_KEY: event_name, output_key: output_text}
+    sys.stdout.write(json.dumps({HOOK_SPECIFIC_OUTPUT_KEY: hook_event_output}))
+
+
+def reply_limit_reminder(session_id: object) -> str:
+    """Return the reply rules, plus the draft the user saw in place of the last reply."""
+    shown_draft_path = state_file_path(SHOWN_DRAFT_FILE_PREFIX, session_id)
+    shown_draft = read_state_text(shown_draft_path)
+    if not shown_draft:
+        return REPLY_LIMIT_REMINDER
+    shown_draft_path.unlink(missing_ok=True)
+    return REPLY_LIMIT_REMINDER + SHOWN_DRAFT_PREFIX + shown_draft
+
+
+def main() -> int:
+    if os.environ.get(DRAFTER_GUARD_ENV_VAR):
+        return ALLOW_EXIT_CODE
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None:
+        return ALLOW_EXIT_CODE
+    event_name = hook_input.get(HOOK_EVENT_NAME_INPUT_KEY)
+    if event_name == USER_PROMPT_SUBMIT_EVENT_NAME:
+        write_hook_output(
+            USER_PROMPT_SUBMIT_EVENT_NAME,
+            ADDITIONAL_CONTEXT_KEY,
+            reply_limit_reminder(hook_input.get(SESSION_ID_KEY)),
+        )
+        return ALLOW_EXIT_CODE
+    if event_name == SESSION_END_EVENT_NAME:
+        state_file_path(SHOWN_DRAFT_FILE_PREFIX, hook_input.get(SESSION_ID_KEY)).unlink(missing_ok=True)
+        return ALLOW_EXIT_CODE
+    if event_name != MESSAGE_DISPLAY_EVENT_NAME:
+        return ALLOW_EXIT_CODE
+    display_text = shown_text(hook_input)
+    if display_text is not None:
+        write_hook_output(MESSAGE_DISPLAY_EVENT_NAME, DISPLAY_CONTENT_KEY, display_text)
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/hooks/blocking/inventory_intent_records/records.py

@@ -33,11 +33,10 @@ from inventory_intent_records.config.intent_records_constants import (
 )
 
 from hooks_constants.session_edit_stage_gate_constants import (
-    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
     STATE_FILE_ATOMIC_WRITE_SUFFIX,
-    STATE_FILE_DEFAULT_SESSION_ID,
     STATE_FILE_JSON_INDENT_SPACES,
 )
+from hooks_constants.session_file_id import session_file_id
 
 
 def _intent_file_path(session_id: str) -> Path:
@@ -50,9 +49,7 @@ def _intent_file_path(session_id: str) -> Path:
     Returns:
         The absolute path of this session's intent-records file.
     """
-    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", session_id)
-    effective_session_id = sanitized_session_id or STATE_FILE_DEFAULT_SESSION_ID
-    file_name = f"{INTENT_FILE_PREFIX}{effective_session_id}{INTENT_FILE_SUFFIX}"
+    file_name = f"{INTENT_FILE_PREFIX}{session_file_id(session_id)}{INTENT_FILE_SUFFIX}"
     return Path(tempfile.gettempdir()) / file_name
 
 

package/hooks/blocking/test_chat_reply_gate.py

@@ -0,0 +1,224 @@
+import io
+import json
+from pathlib import Path
+
+import pytest
+
+import chat_reply_gate
+
+FOUR_SENTENCE_REPLY = "PR one merged. PR two is queued. PR three needs a fix. Nothing else is open."
+THREE_SENTENCE_REPLY = "PR one merged. PR two is queued. Nothing else is open."
+PASSING_DRAFT = "PR one merged. Two others wait."
+
+
+@pytest.fixture(autouse=True)
+def default_banned_words(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> None:
+    monkeypatch.setenv("CLAUDE_REPLY_BANNED_WORDS_PATH", str(tmp_path / "absent.json"))
+    monkeypatch.delenv("CHAT_REPLY_DRAFTER_ACTIVE", raising=False)
+    monkeypatch.setattr(chat_reply_gate, "log_hook_block", lambda *_args, **_kwargs: None)
+    monkeypatch.setattr(chat_reply_gate.tempfile, "gettempdir", lambda: str(tmp_path))
+
+
+def run_hook(
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    hook_input: dict[str, object],
+) -> tuple[int, dict[str, object] | None]:
+    monkeypatch.setattr(
+        "sys.stdin", io.TextIOWrapper(io.BytesIO(json.dumps(hook_input).encode("utf-8")))
+    )
+    exit_code = chat_reply_gate.main()
+    output_text = capsys.readouterr().out
+    return exit_code, json.loads(output_text)["hookSpecificOutput"] if output_text else None
+
+
+def display_input(delta: str, is_final: bool = True) -> dict[str, object]:
+    return {
+        "hook_event_name": "MessageDisplay",
+        "session_id": "abc",
+        "message_id": "m1",
+        "delta": delta,
+        "final": is_final,
+    }
+
+
+def test_should_show_a_passing_draft_in_place_of_a_long_reply(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(chat_reply_gate, "ask_drafter", lambda *_args: PASSING_DRAFT)
+    exit_code, hook_output = run_hook(monkeypatch, capsys, display_input(FOUR_SENTENCE_REPLY))
+    assert exit_code == 0
+    assert hook_output == {"hookEventName": "MessageDisplay", "displayContent": PASSING_DRAFT}
+
+
+def test_should_show_a_reply_within_the_limit_unchanged(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(chat_reply_gate, "ask_drafter", lambda *_args: pytest.fail("drafter called"))
+    exit_code, hook_output = run_hook(monkeypatch, capsys, display_input(THREE_SENTENCE_REPLY))
+    assert exit_code == 0
+    assert hook_output is None
+
+
+def test_should_hold_batches_until_the_last_one_arrives(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    all_requests: list[str] = []
+    monkeypatch.setattr(
+        chat_reply_gate,
+        "ask_drafter",
+        lambda reply_text, _violation: all_requests.append(reply_text) or PASSING_DRAFT,
+    )
+    _, first_output = run_hook(
+        monkeypatch, capsys, display_input("PR one merged. PR two is queued.\n", False)
+    )
+    _, last_output = run_hook(
+        monkeypatch, capsys, display_input("PR three needs a fix. Nothing else is open.")
+    )
+    assert first_output == {"hookEventName": "MessageDisplay", "displayContent": ""}
+    assert last_output == {"hookEventName": "MessageDisplay", "displayContent": PASSING_DRAFT}
+    assert all_requests == [
+        "PR one merged. PR two is queued.\nPR three needs a fix. Nothing else is open."
+    ]
+
+
+def test_should_show_the_whole_held_message_when_it_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    run_hook(monkeypatch, capsys, display_input("PR one merged.\n", False))
+    _, hook_output = run_hook(monkeypatch, capsys, display_input("Nothing else is open."))
+    assert hook_output == {
+        "hookEventName": "MessageDisplay",
+        "displayContent": "PR one merged.\nNothing else is open.",
+    }
+
+
+def test_should_show_the_original_when_no_draft_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    all_calls: list[str] = []
+    monkeypatch.setattr(
+        chat_reply_gate,
+        "ask_drafter",
+        lambda reply_text, _violation: all_calls.append(reply_text) or FOUR_SENTENCE_REPLY,
+    )
+    _, hook_output = run_hook(monkeypatch, capsys, display_input(FOUR_SENTENCE_REPLY))
+    assert hook_output is None
+    assert len(all_calls) == 2
+
+
+def test_should_tell_the_agent_which_draft_the_user_saw(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(chat_reply_gate, "ask_drafter", lambda *_args: PASSING_DRAFT)
+    run_hook(monkeypatch, capsys, display_input(FOUR_SENTENCE_REPLY))
+    prompt_input = {"hook_event_name": "UserPromptSubmit", "session_id": "abc"}
+    _, first_output = run_hook(monkeypatch, capsys, prompt_input)
+    _, second_output = run_hook(monkeypatch, capsys, prompt_input)
+    assert first_output is not None and second_output is not None
+    assert str(first_output["additionalContext"]).endswith(PASSING_DRAFT)
+    assert PASSING_DRAFT not in str(second_output["additionalContext"])
+
+
+def test_should_delete_the_shown_draft_at_session_end(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(chat_reply_gate, "ask_drafter", lambda *_args: PASSING_DRAFT)
+    run_hook(monkeypatch, capsys, display_input(FOUR_SENTENCE_REPLY))
+    shown_draft_path = chat_reply_gate.state_file_path("claude-chat-reply-shown-", "abc")
+    assert shown_draft_path.exists()
+    exit_code, hook_output = run_hook(
+        monkeypatch, capsys, {"hook_event_name": "SessionEnd", "session_id": "abc"}
+    )
+    assert exit_code == 0
+    assert hook_output is None
+    assert not shown_draft_path.exists()
+
+
+def test_should_add_the_reply_limit_on_each_user_prompt(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, hook_output = run_hook(
+        monkeypatch, capsys, {"hook_event_name": "UserPromptSubmit", "prompt": "status?"}
+    )
+    assert exit_code == 0
+    assert hook_output is not None
+    assert hook_output["hookEventName"] == "UserPromptSubmit"
+    assert "3 sentences or fewer" in str(hook_output["additionalContext"])
+
+
+def test_should_do_nothing_inside_the_drafter_process(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setenv("CHAT_REPLY_DRAFTER_ACTIVE", "1")
+    exit_code, hook_output = run_hook(monkeypatch, capsys, display_input(FOUR_SENTENCE_REPLY))
+    assert exit_code == 0
+    assert hook_output is None
+
+
+def test_should_ignore_the_stop_event(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    exit_code, hook_output = run_hook(
+        monkeypatch,
+        capsys,
+        {"hook_event_name": "Stop", "last_assistant_message": FOUR_SENTENCE_REPLY},
+    )
+    assert exit_code == 0
+    assert hook_output is None
+
+
+def test_ask_drafter_should_read_the_result_field(monkeypatch: pytest.MonkeyPatch) -> None:
+    class CompletedDrafter:
+        stdout = json.dumps({"result": f"  {PASSING_DRAFT}\n"})
+
+    all_commands: list[list[str]] = []
+    monkeypatch.setattr(chat_reply_gate.shutil, "which", lambda _name: "C:/npm/claude.cmd")
+    monkeypatch.setattr(
+        chat_reply_gate.subprocess,
+        "run",
+        lambda command, **_kwargs: all_commands.append(command) or CompletedDrafter(),
+    )
+    assert chat_reply_gate.ask_drafter(FOUR_SENTENCE_REPLY, "too long") == PASSING_DRAFT
+    assert all_commands[0][:4] == ["C:/npm/claude.cmd", "-p", "--model", "haiku"]
+
+
+def test_ask_drafter_should_return_none_for_an_error_result(monkeypatch: pytest.MonkeyPatch) -> None:
+    class FailedDrafter:
+        stdout = json.dumps({"is_error": True, "result": "Credit balance is too low"})
+
+    monkeypatch.setattr(chat_reply_gate.subprocess, "run", lambda *_args, **_kwargs: FailedDrafter())
+    assert chat_reply_gate.ask_drafter(FOUR_SENTENCE_REPLY, "too long") is None
+
+
+def test_should_forget_the_shown_draft_when_a_later_reply_passes(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(chat_reply_gate, "ask_drafter", lambda *_args: PASSING_DRAFT)
+    run_hook(monkeypatch, capsys, display_input(FOUR_SENTENCE_REPLY))
+    run_hook(monkeypatch, capsys, {**display_input(THREE_SENTENCE_REPLY), "message_id": "m2"})
+    _, hook_output = run_hook(monkeypatch, capsys, {"hook_event_name": "UserPromptSubmit", "session_id": "abc"})
+    assert hook_output is not None
+    assert PASSING_DRAFT not in str(hook_output["additionalContext"])
+
+
+def test_should_show_a_batch_without_a_message_id_as_it_is(
+    monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
+) -> None:
+    monkeypatch.setattr(chat_reply_gate, "ask_drafter", lambda *_args: pytest.fail("drafter called"))
+    batch_input = {**display_input("PR one merged. PR two", is_final=False), "message_id": None}
+    exit_code, hook_output = run_hook(monkeypatch, capsys, batch_input)
+    assert exit_code == 0
+    assert hook_output is None
+
+
+def test_drafter_environment_should_carry_the_guard(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("CLAUDE_CODE_SESSION_ID", "parent")
+    environment = chat_reply_gate.drafter_environment()
+    assert environment["CHAT_REPLY_DRAFTER_ACTIVE"] == "1"
+    assert "CLAUDE_CODE_SESSION_ID" not in environment
+
+
+def test_state_file_path_should_strip_unsafe_characters(tmp_path: Path) -> None:
+    state_path = chat_reply_gate.state_file_path("claude-chat-reply-held-", "../a b/c")
+    assert state_path == tmp_path / "claude-chat-reply-held-abc.txt"

package/hooks/features/conduct-gates.md

@@ -7,6 +7,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/reply_length_gate.py` caps chat reply length, denies a configured banned word, requires a readable link when the text names a pull request number, and denies a causal claim in a reply that cites no code span, output block, or link. It denies a sentence that guesses, estimates, hedges a duration, or admits a skipped check, such as "I didn't confirm this one." It denies a cited Actions run, pull request, or run, job, or check id that no successful tool result in the transcript shows; a subagent's report is the result of its Agent call. A question card from `AskUserQuestion` gets the banned word check and `unvalidated_claim_violation`, like a decision card. With visual reply mode on, it also runs the checks in `visual_reply_rules.py` from the rule list in `rules/visual-reply-rules.json`: no abbreviation or tracker number outside a link, a widget or page before a reply of more than one sentence, and no anchor link inside widget code. The mode is off by default; `~/.claude/visual-reply-mode.json` with `{"enabled": true}` turns the mode checks on.
 - `blocking/final_reply_gate.py` applies the banned words, `unvalidated_claim_violation`, and `unseen_citation_violation` from the reply gate to the reply a session ends its turn with.
 - The claim judge is a `prompt` hook in `hooks.json`, with no `model` set, so Claude Code's small default hook model reads each chat message and denies the first claim about how code, a file, a tool, a service, a run, or a process behaves, or why something happened, when nothing in the message shows it: inline code that quotes output or a code line, a file and line, or a link. A pull request link covers what that change does, what it blocks or lets through, and its checks. The author's own actions, a restatement of the user's words, questions, instructions, and a decision card's option consequences pass. It catches the plain claims the causal word list in `blocking/reply_length_gate.py` misses, such as "The code lets any of them rewrite it mid-check." `continueOnBlock` returns the reason to the agent as the tool error, so it can add the source and send again. The installer owns it through the `claude-dev-env: ` prefix on its `statusMessage`. It skips `post_widget`, whose input is SVG or HTML markup.
+- `blocking/chat_reply_gate.py` runs the `reply_length_gate.py` reply checks on a plain chat reply, which is no tool call. On `UserPromptSubmit` it adds the reply rules as `additionalContext`. On `MessageDisplay` it holds each streamed batch until the message ends. A message that passes shows whole. A message that fails shows as a draft from `claude -p` on Haiku that passes the same checks, and the original shows when two drafts fail. The draft changes only the text on screen, so the next `UserPromptSubmit` tells the agent the text the user saw, and `SessionEnd` deletes the stored draft. The [reply arena harness](https://github.com/jl-cmd-projects/claude-dev-env/tree/160349b90f627ea542fc6bc7b2b7f86dcbf98b73/tests/reply_arena) ran the comparison that chose this display path.
 - `blocking/edit_marker_gate.py` rejects strikethrough and edit-note markers in replacement chat text or cards.
 - `blocking/issue_close_handoff_gate.py` denies an issue comment or issue write that closes the issue and routes a found defect to another issue or epic.
 - `blocking/session_title_format_gate.py` denies a session title that breaks the `<emoji> <name>` shape or has a name longer than 25 characters.
@@ -23,6 +24,7 @@ This family stops a chat reply, edited message, or tool call when its payload br
 - `blocking/reply_length_gate.py` runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision|AskUserQuestion|mcp__hearthbot__post_widget`, timeout `10` seconds in `hooks.json`.
 - `blocking/final_reply_gate.py` runs on `Stop`, timeout `10` seconds in `hooks.json`.
 - The claim judge runs on `PreToolUse`, matcher `mcp__hearthbot__reply|mcp__hearthbot__post_message|mcp__hearthbot__update_message|mcp__hearthbot__ask_decision`, timeout `30` seconds in `hooks.json`.
+- `blocking/chat_reply_gate.py` runs on `UserPromptSubmit`, matcher empty, timeout `10` seconds, on `MessageDisplay`, timeout `100` seconds, and on `SessionEnd`, timeout `3` seconds, in `hooks.json`.
 - `blocking/edit_marker_gate.py` runs on `PreToolUse`, matcher `mcp__.*__update_message`, timeout `10` seconds in `hooks.json`.
 - `blocking/issue_close_handoff_gate.py` runs on `PreToolUse`, matcher `mcp__.*__(add_issue_comment|issue_write|update_issue_comment)`, timeout `10` seconds in `hooks.json`.
 - `blocking/session_title_format_gate.py` runs on `PreToolUse`, matcher `mcp__.*__set_session_title`, timeout `10` seconds in `hooks.json`.
@@ -43,6 +45,7 @@ Preconditions:
 - **Reply length.** Input is a reply with four sentences, a plain pull request number, an abbreviation, two sentences with no widget this turn, or widget code with an anchor link. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_reply_length_gate.py -q`. The adjacent test observes a denial and its count, link, or mode reason. Widget code with no flowchart passes with a flowchart reminder in `additionalContext`.
 - **Final reply.** Input is a closing reply that says "My guess is one to two hours." or cites a run no tool result shows. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_final_reply_gate.py -q`. The adjacent test observes a `block` decision that quotes the sentence or the citation; a reply that cites a run a tool result shows passes.
 - **Claim judge.** Input is a headless `claude -p` session with a stub MCP server named `hearthbot` that exposes `reply` and `ask_decision`, told to send "The code lets any of them rewrite it mid-check." The session settings add the `hooks.json` prompt hook. The stub logs zero bytes sent, and the tool error reads `PreToolUse:mcp__hearthbot__reply hook error: [<the prompt>]: Fact with no source: ...`. The same sentence with a `file:line` in backticks posts. A hook whose `model` Claude Code does not recognize lets every message through, so leave `model` unset. Run `node --test packages/claude-dev-env/bin/install.prompt-hook.test.mjs` for the installer side; it observes one managed prompt hook after two installs and none after uninstall.
+- **Chat reply.** Input is a `MessageDisplay` event whose message holds four sentences, the same message split over two batches, and a `UserPromptSubmit` event. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_chat_reply_gate.py -q`. The adjacent test observes the drafter's text in `displayContent`, an empty first batch, no output for three sentences, the original after two failed drafts, the shown draft in the next `additionalContext`, and the stored draft deleted at session end.
 - **Edit marker.** Input is an update message with strikethrough or an edit note. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_edit_marker_gate.py -q`. The adjacent test observes a denial; clean replacement text passes.
 - **Handoff close.** Input is an issue comment that says the issue is closed and that the found defect belongs to another issue. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_issue_close_handoff_gate.py -q`. The adjacent test observes a denial; a close with a plain cross-reference and a routing comment on an open issue both pass.
 - **Session title.** Input is a set session title call with no leading emoji or a name over 25 characters. Run `python -m pytest packages/claude-dev-env/hooks/blocking/test_session_title_format_gate.py -q`. The adjacent test observes a denial that names the broken rule; a well-formed title passes.

package/hooks/hooks.json

@@ -293,6 +293,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/lifecycle/nested_project_hooks.py",
             "timeout": 120
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/chat_reply_gate.py",
+            "timeout": 10
           }
         ]
       }
@@ -391,6 +396,11 @@
             "type": "command",
             "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/session/session_edit_tracker_cleanup.py",
             "timeout": 3
+          },
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/chat_reply_gate.py",
+            "timeout": 3
           }
         ]
       }
@@ -470,6 +480,17 @@
           }
         ]
       }
+    ],
+    "MessageDisplay": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 ${CLAUDE_PLUGIN_ROOT}/hooks/blocking/chat_reply_gate.py",
+            "timeout": 100
+          }
+        ]
+      }
     ]
   }
 }

package/hooks/hooks_constants/chat_reply_gate_constants.py

@@ -0,0 +1,58 @@
+"""Constants for the chat reply gate UserPromptSubmit and MessageDisplay hook."""
+
+from hooks_constants.reply_length_gate_constants import (
+    MAXIMUM_SENTENCE_COUNT,
+    MAXIMUM_WORDS_PER_SENTENCE,
+)
+
+HOOK_EVENT_NAME_INPUT_KEY = "hook_event_name"
+MESSAGE_DISPLAY_EVENT_NAME = "MessageDisplay"
+USER_PROMPT_SUBMIT_EVENT_NAME = "UserPromptSubmit"
+SESSION_END_EVENT_NAME = "SessionEnd"
+SESSION_ID_KEY = "session_id"
+MESSAGE_ID_KEY = "message_id"
+DELTA_KEY = "delta"
+FINAL_KEY = "final"
+DISPLAY_CONTENT_KEY = "displayContent"
+STATE_FILE_ENCODING = "utf-8"
+HELD_TEXT_FILE_PREFIX = "claude-chat-reply-held-"
+SHOWN_DRAFT_FILE_PREFIX = "claude-chat-reply-shown-"
+STATE_FILE_SUFFIX = ".txt"
+REPLY_LIMIT_REMINDER = (
+    f"Your reply to the user is final and gets no second pass. Keep it to {MAXIMUM_SENTENCE_COUNT}"
+    f" sentences or fewer, each {MAXIMUM_WORDS_PER_SENTENCE} words or fewer."
+    " Each line and each list item counts as one sentence, so prefer short prose over lists."
+    " Lead with the outcome and cut detail the user did not ask for."
+    " No colon in the middle of a sentence, and no em dash."
+    " Put any pull request number inside a markdown link."
+    " A sentence with so, because, caused, due to, therefore, or means needs inline code, a URL, or a link in it."
+    " Never write real, really, genuine, actual, actually, likely, probably, seems, maybe, perhaps, may be, or might be."
+    " Count your sentences before you send."
+)
+SHOWN_DRAFT_PREFIX = "\n\nThe user saw your last reply condensed to this text, so build on it:\n\n"
+DRAFTER_GUARD_ENV_VAR = "CHAT_REPLY_DRAFTER_ACTIVE"
+DRAFTER_MODEL_ENV_VAR = "CHAT_REPLY_DRAFTER_MODEL"
+DEFAULT_DRAFTER_MODEL = "haiku"
+DRAFTER_TIMEOUT_SECONDS = 45
+MAXIMUM_DRAFT_ATTEMPTS = 2
+DRAFTER_RESULT_KEY = "result"
+DRAFTER_ERROR_KEY = "is_error"
+DRAFTER_EXECUTABLE_NAME = "claude"
+CLAUDE_SESSION_ID_ENV_VAR = "CLAUDE_CODE_SESSION_ID"
+DRAFTER_REQUEST_TEMPLATE = "Rule the reply broke: {violation}\n\nReply to rewrite:\n\n{reply_text}"
+DRAFTER_RULES = (
+    f"Rewrite the reply below so it obeys every rule. At most {MAXIMUM_SENTENCE_COUNT} sentences,"
+    f" each at most {MAXIMUM_WORDS_PER_SENTENCE} words. Each line and each list item counts as one sentence."
+    " Keep the outcome, the recommendation, and any number, path, or command the user needs."
+    " Drop background the user did not ask for."
+    " No colon in the middle of a sentence. No em dash."
+    " Write a pull request number only inside a markdown link."
+    " A sentence that gives a cause, with so, because, caused, due to, therefore, or means,"
+    " must hold its own evidence as inline code, a URL, or a markdown link. Otherwise state the fact without the cause word."
+    " Never use these words: real, really, genuine, actual, actually, likely, probably, seems, maybe, perhaps,"
+    " might be, may be, appears to, suspect, guess, presumably."
+    " Speak as the original author to the original reader."
+    " Never mention the rule, the length, or this rewrite."
+    " Never add, drop, or change a fact, a command, a flag, or a file name; leave out a whole point instead."
+    " Return only the rewritten reply, with no preface."
+)

package/hooks/hooks_constants/session_file_id.py

@@ -0,0 +1,17 @@
+"""Turn a hook payload's session id into a safe part of a temp file name."""
+
+from __future__ import annotations
+
+from hooks_constants.session_edit_stage_gate_constants import (
+    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
+    STATE_FILE_DEFAULT_SESSION_ID,
+)
+
+__all__ = ["session_file_id"]
+
+
+def session_file_id(session_id: object) -> str:
+    """Return the session id with unsafe characters stripped, or the default id when none remain."""
+    raw_session_id = session_id if isinstance(session_id, str) else ""
+    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", raw_session_id)
+    return sanitized_session_id or STATE_FILE_DEFAULT_SESSION_ID

package/hooks/hooks_constants/test_session_file_id.py

@@ -0,0 +1,17 @@
+"""Tests for the shared session id that names per-session temp files."""
+
+from __future__ import annotations
+
+from hooks_constants.session_file_id import session_file_id
+
+
+def test_should_strip_path_characters_from_the_session_id() -> None:
+    assert session_file_id("../a b/c-1_2") == "abc-1_2"
+
+
+def test_should_fall_back_to_the_default_id_when_nothing_safe_remains() -> None:
+    assert session_file_id("../ /") == "default"
+
+
+def test_should_fall_back_to_the_default_id_for_a_missing_session_id() -> None:
+    assert session_file_id(None) == "default"

package/hooks/observability/session_file_edit_tracker.py

@@ -39,11 +39,10 @@ from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
     APPLY_PATCH_TOOL_NAME,
     SESSION_EDIT_FILE_PREFIX,
     SESSION_EDIT_FILE_SUFFIX,
-    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
     STATE_FILE_ATOMIC_WRITE_SUFFIX,
-    STATE_FILE_DEFAULT_SESSION_ID,
     STATE_FILE_JSON_INDENT_SPACES,
 )
+from hooks_constants.session_file_id import session_file_id
 
 
 def _resolved_path_or_none(file_path: str) -> str | None:
@@ -74,9 +73,7 @@ def _session_edit_file_path(session_id: str) -> Path:
     Returns:
         Absolute path to this session's tracker file.
     """
-    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", session_id)
-    effective_session_id = sanitized_session_id or STATE_FILE_DEFAULT_SESSION_ID
-    file_name = f"{SESSION_EDIT_FILE_PREFIX}{effective_session_id}{SESSION_EDIT_FILE_SUFFIX}"
+    file_name = f"{SESSION_EDIT_FILE_PREFIX}{session_file_id(session_id)}{SESSION_EDIT_FILE_SUFFIX}"
     return Path(tempfile.gettempdir()) / file_name
 
 

package/hooks/session/session_edit_tracker_cleanup.py

@@ -35,11 +35,10 @@ from hooks_constants.pre_tool_use_stdin import (  # noqa: E402
 from hooks_constants.session_edit_stage_gate_constants import (  # noqa: E402
     SESSION_EDIT_FILE_PREFIX,
     SESSION_EDIT_FILE_SUFFIX,
-    SESSION_ID_UNSAFE_CHARACTERS_PATTERN,
     SESSION_START_SOURCE_FRESH_STARTUP,
     SESSION_START_SOURCE_PAYLOAD_KEY,
-    STATE_FILE_DEFAULT_SESSION_ID,
 )
+from hooks_constants.session_file_id import session_file_id
 
 
 def _delete_file(target_file: Path) -> None:
@@ -66,9 +65,7 @@ def _current_session_file_name(session_id: str) -> str:
         The tracker file name for the sanitized session id, falling back to
         the default id when sanitizing leaves an empty string.
     """
-    sanitized_session_id = SESSION_ID_UNSAFE_CHARACTERS_PATTERN.sub("", session_id)
-    effective_session_id = sanitized_session_id or STATE_FILE_DEFAULT_SESSION_ID
-    return f"{SESSION_EDIT_FILE_PREFIX}{effective_session_id}{SESSION_EDIT_FILE_SUFFIX}"
+    return f"{SESSION_EDIT_FILE_PREFIX}{session_file_id(session_id)}{SESSION_EDIT_FILE_SUFFIX}"
 
 
 def _is_tracker_deletion_lifecycle_event(payload_by_field: dict[str, object]) -> bool:

package/package.json

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

package/scripts/policy_lint/adapter_configuration.py

@@ -130,6 +130,7 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
         hooks/blocking/pr_lifecycle_skill_gate.py        -> exempt
         hooks/blocking/step_note_gate.py                 -> exempt
         hooks/blocking/reply_length_gate.py              -> exempt
+        hooks/blocking/chat_reply_gate.py                -> exempt
         hooks/blocking/edit_marker_gate.py               -> exempt
         hooks/blocking/issue_close_handoff_gate.py       -> exempt
         hooks/blocking/verify_before_acting.py           -> exempt
@@ -154,7 +155,8 @@ def _names_exempt_registration_path(registered_string: str) -> bool:
     It asks for a readable status line and decides no code or safety policy.
 
     The reply length gate caps the sentences in a chat reply to the user. It
-    decides the shape of prose and no code or safety policy.
+    decides the shape of prose and no code or safety policy. The chat reply
+    gate runs the same checks on a reply typed straight into the chat.
 
     The edit marker gate keeps strikethrough and edit notes out of an edited
     chat message. It decides the shape of prose and no code or safety policy.

package/scripts/policy_lint/config/constants.py

@@ -67,6 +67,7 @@ ALL_ACTION_BOUNDARY_EXEMPT_REGISTRATION_PATHS = (
     "blocking/merge_review_gate.py",
     "blocking/step_note_gate.py",
     "blocking/reply_length_gate.py",
+    "blocking/chat_reply_gate.py",
     "blocking/edit_marker_gate.py",
     "blocking/issue_close_handoff_gate.py",
     "blocking/verify_before_acting.py",

package/scripts/tests/test_adapter_configuration.py

@@ -90,6 +90,14 @@ def test_new_reply_length_gate_registration_is_clean(tmp_path: Path) -> None:
     assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
 
 
+def test_new_chat_reply_gate_registration_is_clean(tmp_path: Path) -> None:
+    current_document = _hook_document(
+        ["hooks/blocking/chat_reply_gate.py"],
+        '{"hooks": {}}',
+    )
+    assert adapters.hook_configuration_diagnostics(current_document, tmp_path) == ()
+
+
 def test_new_edit_marker_gate_registration_is_clean(tmp_path: Path) -> None:
     current_document = _hook_document(
         ["hooks/blocking/edit_marker_gate.py"],