claude-dev-env 8.87.1 → 8.88.0

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

@@ -9,9 +9,11 @@ import {
     DEEPSTACK_PLUGIN_SPEC,
     deepStackCloneUrl,
     deepStackInstallPlan,
+    deepStackCursorSessionCommand,
     installDeepStackCursor,
     installDeepStackForHosts,
     mergeDeepStackCursorHooks,
+    removeDeepStackCursorHooks,
 } from './install-deepstack-plugin.mjs';
 import { marketplacePluginsPlan, shouldInstallMarketplacePlugin } from './install-pstack-plugin.mjs';
 
@@ -32,18 +34,47 @@ test('Claude and Codex plans name jl-cmd-projects/DeepStack', () => {
     assert.throws(() => marketplacePluginsPlan([DEEPSTACK_PLUGIN_SPEC], 'cursor'), /cursor/);
 });
 
-test('cursor hooks keep the session hook and the first-task gate', () => {
-    const merged = mergeDeepStackCursorHooks({ hooks: { PreToolUse: [] } }, {
+test('cursor hooks are one native sessionStart entry and one native beforeSubmitPrompt entry', () => {
+    const legacySessionGroup = {
+        matcher: 'startup|resume|clear|compact',
+        hooks: [{ type: 'command', command: "'C:\\Users\\dev\\.cursor\\plugins\\deepstack\\hooks\\session-start.sh' cursor" }],
+    };
+    const commands = {
         sessionCommand: "'/cursor/plugins/deepstack/hooks/session-start.sh' cursor",
         firstTaskCommand: "python3 '/claude/hooks/session/deepen_first_prompt.py'",
+    };
+    const merged = mergeDeepStackCursorHooks({
+        hooks: {
+            SessionStart: [legacySessionGroup, legacySessionGroup, legacySessionGroup],
+            UserPromptSubmit: [{ matcher: '', hooks: [{ type: 'command', command: 'python3 /old/deepen_first_prompt.py', timeout: 10 }] }],
+            preToolUse: [],
+        },
+    }, commands);
+    assert.deepEqual(merged, {
+        version: 1,
+        hooks: {
+            sessionStart: [{ command: commands.sessionCommand, timeout: 10 }],
+            beforeSubmitPrompt: [{ command: commands.firstTaskCommand, timeout: 10 }],
+            preToolUse: [],
+        },
     });
-    assert.deepEqual(Object.keys(merged.hooks).sort(), ['PreToolUse', 'SessionStart', 'UserPromptSubmit']);
-    const text = JSON.stringify(merged);
-    assert.match(text, /session-start\.sh/);
-    assert.match(text, /deepen_first_prompt\.py/);
+    assert.deepEqual(mergeDeepStackCursorHooks(merged, commands), merged);
 });
 
-test('the cursor copy writes the skill and both hook commands', () => {
+test('the Windows session command runs the PowerShell script, other platforms the shell script', () => {
+    const root = mkdtempSync(join(tmpdir(), 'deepstack-cursor-'));
+    try {
+        mkdirSync(join(root, 'hooks'), { recursive: true });
+        writeFileSync(join(root, 'hooks', 'session-start.ps1'), 'param()\n');
+        const forwardSlashed = pathValue => `"${pathValue.replace(/\\/g, '/')}"`;
+        assert.match(deepStackCursorSessionCommand(root, forwardSlashed, 'win32'), /^powershell -NoProfile -ExecutionPolicy Bypass -File ".*hooks\/session-start\.ps1" cursor$/);
+        assert.match(deepStackCursorSessionCommand(root, forwardSlashed, 'linux'), /hooks\/session-start\.sh" cursor$/);
+    } finally {
+        rmSync(root, { recursive: true, force: true });
+    }
+});
+
+test('the cursor copy writes the skill and both native hook commands, and removal takes out only those', () => {
     const root = mkdtempSync(join(tmpdir(), 'deepstack-cursor-'));
     try {
         const source = join(root, 'source');
@@ -52,10 +83,14 @@ test('the cursor copy writes the skill and both hook commands', () => {
         writeFileSync(join(source, 'skills', 'deepstack-mode', 'SKILL.md'), 'DeepStack intake\n');
         writeFileSync(join(source, 'hooks', 'session-start.sh'), '#!/bin/sh\n');
         const cursorDirectory = join(root, '.cursor');
+        mkdirSync(cursorDirectory, { recursive: true });
+        writeFileSync(join(cursorDirectory, 'hooks.json'), JSON.stringify({ version: 1, hooks: { stop: [{ command: './user-stop.sh' }] } }));
         const outcome = installDeepStackCursor({
             cursorDirectory,
             pluginSourceDirectory: source,
             firstTaskHookPath: join(root, '.agents', 'hooks', 'session', 'deepen_first_prompt.py'),
+            pythonCommand: '/usr/bin/python3.12',
+            platform: 'linux',
         });
         assert.equal(outcome.status, 'installed');
         assert.equal(
@@ -63,10 +98,15 @@ test('the cursor copy writes the skill and both hook commands', () => {
             'DeepStack intake\n',
         );
         const hooks = JSON.parse(readFileSync(join(cursorDirectory, 'hooks.json'), 'utf8'));
-        const text = JSON.stringify(hooks);
-        assert.match(text, /session-start\.sh/);
-        assert.match(text, /deepen_first_prompt\.py/);
-        assert.equal(hooks.hooks.SessionStart[0].hooks[0].command.endsWith(' cursor'), true);
+        assert.equal(hooks.version, 1);
+        assert.equal(hooks.hooks.sessionStart.length, 1);
+        assert.match(hooks.hooks.sessionStart[0].command, /session-start\.sh' cursor$/);
+        assert.match(hooks.hooks.beforeSubmitPrompt[0].command, /^\/usr\/bin\/python3\.12 '.*deepen_first_prompt\.py'$/);
+        removeDeepStackCursorHooks(cursorDirectory);
+        assert.deepEqual(
+            JSON.parse(readFileSync(join(cursorDirectory, 'hooks.json'), 'utf8')),
+            { version: 1, hooks: { stop: [{ command: './user-stop.sh' }] } },
+        );
     } finally {
         rmSync(root, { recursive: true, force: true });
     }

package/bin/install.cursor-rules.test.mjs

@@ -12,7 +12,7 @@ import {
 import { tmpdir } from 'node:os';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { execFileSync } from 'node:child_process';
+import { execFileSync, execSync } from 'node:child_process';
 import {
     resolveInstallRoot,
 } from './resolve-install-root.mjs';
@@ -135,7 +135,10 @@ test('seeds one editable policy and one native Codex routing hook', () => {
         );
         assert.equal(firstSpawnPromptGroups.length, 1);
         assert.match(firstSpawnPromptGroups[0].hooks[0].command, /skill_loaded_reminder\.py/);
-        assert.deepEqual(Object.keys(firstCodexHooks.hooks), ['PreToolUse', 'UserPromptSubmit']);
+        assert.deepEqual(Object.keys(firstCodexHooks.hooks), ['PreToolUse', 'UserPromptSubmit', 'Stop']);
+        const allCodexStopCommands = firstCodexHooks.hooks.Stop.flatMap(group => group.hooks.map(hook => hook.command));
+        assert.equal(allCodexStopCommands.length, 1, 'Codex gets the open tasks Stop gate and no other Stop hook');
+        assert.match(allCodexStopCommands[0], /open_tasks_stop_gate\.py/);
         assert.ok(
             firstCodexHooks.hooks.UserPromptSubmit.some(group =>
                 group.hooks.some(hook => String(hook.command).includes('deepen_first_prompt.py')),
@@ -303,6 +306,10 @@ test('Codex reinstall removes omitted package hooks and preserves user configura
             .map(eachHook => eachHook.command);
         assert.ok(allPackagePromptCommands.some(eachCommand => eachCommand.includes('deepen_first_prompt.py')));
         delete migratedHooks.hooks.UserPromptSubmit;
+        const allPackageStopGroups = migratedHooks.hooks.Stop.filter(eachGroup =>
+            eachGroup.hooks.some(eachHook => eachHook.command.includes('open_tasks_stop_gate.py')));
+        assert.equal(allPackageStopGroups.length, 1);
+        migratedHooks.hooks.Stop = migratedHooks.hooks.Stop.filter(eachGroup => !allPackageStopGroups.includes(eachGroup));
         assert.deepEqual(migratedHooks, { enabled: false, metadata: 'keep-file', hooks: expectedUserHooks });
         assert.equal(readFileSync(configPath, 'utf8'), disabledConfig);
         const firstInstall = readFileSync(codexHooksPath, 'utf8');
@@ -518,3 +525,59 @@ test('a blocked shared rule destination fails the install and keeps the existing
     }
 });
 
+
+test('a full install writes only native Cursor hooks: AGENTS.md on sessionStart and the open tasks gate on stop; uninstall removes exactly those', () => {
+    const homeDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-guidance-'));
+    try {
+        const cursorHooksPath = join(homeDirectory, DEFAULT_CURSOR_DIRECTORY_NAME, 'hooks.json');
+        mkdirSync(dirname(cursorHooksPath), { recursive: true });
+        const userStopEntry = { command: './user-stop.sh' };
+        writeFileSync(cursorHooksPath, JSON.stringify({
+            hooks: {
+                SessionStart: [{
+                    matcher: 'startup|resume|clear|compact',
+                    hooks: [{ type: 'command', command: "python3 '/old/hooks/session/cursor_agents_guidance.py' AGENTS.md" }],
+                }, {
+                    matcher: 'startup|resume|clear|compact',
+                    hooks: [{ type: 'command', command: "'/old/.cursor/plugins/deepstack/hooks/session-start.sh' cursor" }],
+                }],
+                UserPromptSubmit: [{
+                    matcher: '',
+                    hooks: [{ type: 'command', command: "python3 '/old/hooks/session/deepen_first_prompt.py'", timeout: 10 }],
+                }],
+                stop: [userStopEntry],
+            },
+        }));
+        runInstaller(homeDirectory, []);
+        const cursorHooks = JSON.parse(readFileSync(cursorHooksPath, 'utf8'));
+        assert.equal(cursorHooks.version, 1);
+        for (const [eventName, allEntries] of Object.entries(cursorHooks.hooks)) {
+            assert.match(eventName, /^[a-z]/, `${eventName} is a Cursor event name`);
+            for (const eachEntry of allEntries) assert.equal(typeof eachEntry.command, 'string', 'every entry is a flat native entry');
+        }
+        const guidanceCommands = cursorHooks.hooks.sessionStart
+            .map(entry => entry.command)
+            .filter(command => command.includes('cursor_agents_guidance.py'));
+        assert.equal(guidanceCommands.length, 1);
+        const guidancePath = join(homeDirectory, '.agents', 'AGENTS.md');
+        assert.ok(guidanceCommands[0].replace(/\\/g, '/').includes(guidancePath.replace(/\\/g, '/')));
+        assert.match(readFileSync(guidancePath, 'utf8'), /\*\*Asks\*\*/);
+        const sessionOutput = execSync(guidanceCommands[0], { input: '{}', encoding: 'utf8' });
+        assert.equal(JSON.parse(sessionOutput).additional_context, readFileSync(guidancePath, 'utf8'));
+        const gateCommands = cursorHooks.hooks.stop.map(entry => entry.command).filter(command => command.includes('open_tasks_stop_gate.py'));
+        assert.equal(gateCommands.length, 1);
+        assert.deepEqual(cursorHooks.hooks.stop.filter(entry => entry.command === userStopEntry.command), [userStopEntry]);
+        assert.equal(execSync(gateCommands[0], { input: '{"conversation_id": "c-1", "status": "completed"}', encoding: 'utf8' }), '');
+        assert.deepEqual(cursorHooks.hooks.beforeSubmitPrompt, [{ command: "python3 '/old/hooks/session/deepen_first_prompt.py'", timeout: 10 }]);
+
+        runInstaller(homeDirectory, ['--uninstall']);
+        const remainingHooks = JSON.parse(readFileSync(cursorHooksPath, 'utf8'));
+        assert.equal(JSON.stringify(remainingHooks).includes('cursor_agents_guidance.py'), false);
+        assert.equal(JSON.stringify(remainingHooks).includes('open_tasks_stop_gate.py'), false);
+        assert.equal(JSON.stringify(remainingHooks).includes('deepen_first_prompt.py'), false);
+        assert.equal(JSON.stringify(remainingHooks).includes('plugins/deepstack/hooks/session-start'), false);
+        assert.deepEqual(remainingHooks.hooks.stop, [userStopEntry]);
+    } finally {
+        rmSync(homeDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install.mjs

@@ -51,6 +51,7 @@ import {
     WINDOWS_PYTHON_LAUNCHER_COMMAND,
     PYTHON_PROBE_TIMEOUT_MILLISECONDS,
     ALL_CODEX_NATIVE_PRE_TOOL_USE_MATCHERS,
+    ALL_CODEX_NATIVE_STOP_HOOK_SCRIPT_NAMES,
 } from './install-constants.mjs';
 import {
     PSTACK_PLUGIN_SPEC,
@@ -63,8 +64,13 @@ import {
 import {
     DEEPSTACK_PLUGIN_SPEC,
     installDeepStackForHosts,
+    removeDeepStackCursorHooks,
 } from './install-deepstack-plugin.mjs';
 import { seedCodexPstackModels } from './seed-codex-pstack-models.mjs';
+import {
+    removeCursorAgentsGuidanceHooks,
+    writeCursorAgentsGuidanceHooks,
+} from './cursor-agents-guidance.mjs';
 import {
     codexSolSettingSnapshotPaths,
     removeCodexSolSetting,
@@ -2214,6 +2220,18 @@ function mergeHooksAtPath(
     return groupCount;
 }
 
+function isCodexNativeStopHook(hook) {
+    const scriptName = String(hook?.command ?? '').replace(/\\/g, '/').split('/').pop();
+    return ALL_CODEX_NATIVE_STOP_HOOK_SCRIPT_NAMES.has(scriptName);
+}
+
+function selectCodexNativeStopGroups(stopGroups) {
+    if (!Array.isArray(stopGroups)) return [];
+    return stopGroups
+        .map(group => ({ ...group, hooks: (group?.hooks ?? []).filter(isCodexNativeStopHook) }))
+        .filter(group => group.hooks.length > 0);
+}
+
 function selectCodexNativeHooksConfig(hooksConfig) {
     const preToolUseGroups = hooksConfig.hooks?.PreToolUse;
     const userPromptSubmitGroups = hooksConfig.hooks?.UserPromptSubmit;
@@ -2224,6 +2242,7 @@ function selectCodexNativeHooksConfig(hooksConfig) {
                 ? preToolUseGroups.filter(group => ALL_CODEX_NATIVE_PRE_TOOL_USE_MATCHERS.has(group?.matcher))
                 : [],
             UserPromptSubmit: Array.isArray(userPromptSubmitGroups) ? userPromptSubmitGroups : [],
+            Stop: selectCodexNativeStopGroups(hooksConfig.hooks?.Stop),
         },
     };
 }
@@ -2919,6 +2938,18 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
     }
     const packageGuidanceText = selectedGroups ? '' : readFileSync(join(PACKAGE_ROOT, 'AGENTS.md'), 'utf8');
     const allPackageGuidancePaths = [join(CLAUDE_HOME, 'AGENTS.md'), join(AGENTS_HOME, 'AGENTS.md')];
+    if (!selectedGroups) {
+        const cursorGuidanceHooksPath = writeCursorAgentsGuidanceHooks({
+            cursorDirectory: INSTALL_ROOT_RESOLUTION.cursorInstallDirectory,
+            hooksDirectory: INSTALL_ROOT_RESOLUTION.hooksInstallDirectory,
+            guidancePath: join(AGENTS_HOME, 'AGENTS.md'),
+            pythonCommand,
+            formatPathArgument: commandArgumentFromPath,
+        });
+        if (cursorGuidanceHooksPath) {
+            console.log(`  \u2713 ${cursorGuidanceHooksPath} (Cursor agents guidance and open tasks hooks)`);
+        }
+    }
     if (!selectedGroups && shouldInstallMarketplacePlugin(PSTACK_PLUGIN_SPEC)) {
         const pstackPlugin = installPstackPluginForHosts();
         summary.pstackPlugin = pstackPlugin;
@@ -2953,6 +2984,8 @@ function executeInstallPlanMutations(plan, transactionHelpers) {
                 'session',
                 'deepen_first_prompt.py',
             ),
+            pythonCommand,
+            formatPathArgument: commandArgumentFromPath,
         });
         summary.deepStackPlugin = deepStackPlugin;
         printPluginHostOutcomes([DEEPSTACK_PLUGIN_SPEC], deepStackPlugin);
@@ -3399,6 +3432,8 @@ function executeUninstallPlan(plan, helpers = {}) {
         pruneManagedHooksFromHostConfiguration(CODEX_HOOKS_CONFIGURATION_PATH, 2);
     }
     removeRetiredSessionContinuityHooks(['codex', 'cursor']);
+    removeCursorAgentsGuidanceHooks(INSTALL_ROOT_RESOLUTION.cursorInstallDirectory);
+    removeDeepStackCursorHooks(INSTALL_ROOT_RESOLUTION.cursorInstallDirectory);
     throwIfFault(FAULT_PHASES.AFTER_SETTINGS_WRITE);
 
     unsetGlobalGitHooksPathIfOurs();

package/bin/install.test.mjs

@@ -3208,11 +3208,16 @@ test('a full install adds DeepStack for Claude, Codex, and Cursor', t => {
         'DeepStack intake\n',
     );
     const hooks = JSON.parse(readFileSync(join(sandbox.homeDirectory, '.cursor', 'hooks.json'), 'utf8'));
-    const hookText = JSON.stringify(hooks);
-    assert.match(hookText, /session-start\.sh/);
-    assert.match(hookText, /SessionStart/);
-    assert.match(hookText, /deepen_first_prompt\.py/);
-    assert.match(hookText, /UserPromptSubmit/);
+    assert.equal(hooks.version, 1);
+    assert.deepEqual(
+        hooks.hooks.sessionStart.filter(entry => entry.command.includes('session-start.sh')).length,
+        1,
+    );
+    assert.equal(
+        hooks.hooks.beforeSubmitPrompt.filter(entry => entry.command.includes('deepen_first_prompt.py')).length,
+        1,
+    );
+    assert.equal(JSON.stringify(hooks).includes('"hooks":[{'), false, 'no Claude-style group entries');
     const sheet = readFileSync(join(sandbox.homeDirectory, '.codex', 'deepstack-models.md'), 'utf8');
     assert.match(sheet, /^session hook: on$/m);
 });

package/docs/agents-guidance/asks.md

@@ -0,0 +1,49 @@
+# Asks
+
+**When this applies:** Every ask from the user, in every session and every host (Claude Code, Codex, Cursor).
+
+## Rule
+
+- Work every ask as soon as it arrives, and keep working it until it is done with proof you saw. Asks have no due dates and no deadlines. Every ask is worked now, continuously.
+- Stop working an ask only when it is done with proof, or when it is blocked on something only the user can give: a decision, an approval, an account, or a credential. Put a blocked ask in front of the user in the same reply.
+- "Later", "next time", "follow-up", and "parked" are not outcomes.
+- Record each ask as one item in the session tracker: `TaskCreate`, `TodoWrite`, or the Codex `update_plan` tool. Mark an item completed only after you saw the proof.
+- A turn ends only when every item is completed, or the reply ends with one line per item that is not:
+  - `Blocked: <item> - <what the user must give>`
+  - `Open: <item> - <the step you take next>`
+- An `Open:` line is a report. Take its next step at once.
+
+## Asks ledger
+
+When the host keeps an asks ledger with `ledger.py` and `asks_check.py`, record each ask in it too:
+
+- Record work as it happens with `ledger.py update --id <id> --progress --note "<what was done>"`. A status, owner, or note edit without `--progress` is not progress.
+- Close an ask only with `ledger.py close --id <id> --proof <proof>`.
+- Before you report or end a turn, run `asks_check.py --agent <your agent name> --self <your agent name>`. Act on every flagged row now, or put it in front of the user in this reply.
+
+## Enforcement
+
+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.
+- 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.
+
+The gate reads the task list from the task store, the transcript TaskCreate, TaskUpdate, and TodoWrite calls, or the Codex `update_plan` calls. It ends the hold when each open item is named on a `Blocked:` or `Open:` line of the closing reply.
+
+## Cursor
+
+Cursor keeps user rules in its app settings. The installer adds a native `sessionStart` entry, `cursor_agents_guidance.py`, that feeds the installed `AGENTS.md` to each Cursor session as `additional_context`.
+
+What has been seen to work, in an interactive `cursor-agent` session (version 2026.10.16, Windows):
+
+- 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.
+
+Limits:
+
+- `cursor-agent -p` (print mode) does not send `stop` or `beforeSubmitPrompt`, so the gate never runs there.
+- The Cursor editor has not been tested.
+- Cursor also runs the hooks in `~/.claude/settings.json` by default. When Claude Code hooks from this package are installed in the same home, the gate runs twice at each Cursor stop. A stop hook that comes from that file has no follow-up limit in Cursor, so the gate passes once `loop_count` reaches 5.
+- One entry in the Claude Code format inside `~/.cursor/hooks.json` makes Cursor skip every hook in that file. The installer writes only native entries and converts older ones.

package/hooks/blocking/open_tasks_stop_gate.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""Stop hook that keeps a session working while its task list has unreported open items.
+
+The session's task list comes from the first of these that exists::
+
+    ~/.claude/tasks/<task list id>/*.json     (TaskCreate / TaskUpdate store)
+    transcript TaskCreate / TaskUpdate calls   (replayed in order)
+    transcript TodoWrite input.todos           (last call wins)
+    transcript Codex update_plan arguments     (last call wins)
+
+An item with status ``pending`` or ``in_progress`` is open. The turn may end
+only when the closing reply names every open item on a report line::
+
+    allow: Blocked: Rotate the deploy key - the owner must approve the org secret
+    allow: - Open: #3 - waits on the release checks
+    block: (reply never mentions "Rotate the deploy key")
+
+A block sends the open items back as the reason, so the model keeps working or
+reports them. Claude Code ends the turn after eight blocks in a row. Codex
+turns the reason into a continuation prompt. A Cursor payload (it carries
+``conversation_id``) also gets the reason as ``followup_message``, which
+Cursor submits as the next user message; Cursor sends no closing reply, so
+the gate reads the last assistant text from the transcript. A Cursor payload
+whose ``status`` is ``aborted`` or ``error`` is allowed, because Cursor would
+submit the follow-up after the user stopped the run, and so is one whose
+``loop_count`` shows five follow-ups already sent. A TodoWrite call with
+``merge`` set updates the earlier items by id, and a Cursor ``CallDynamicTool``
+call that wraps TodoWrite counts as that TodoWrite call.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import sys
+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 hooks_constants.hook_block_logger import log_hook_block
+from hooks_constants.pre_tool_use_stdin import read_hook_input_dictionary_from_stdin
+from open_tasks_transcript import TaskItem, parsed_object, replayed_transcript
+from hooks_constants.open_tasks_stop_gate_constants import (
+    ALLOW_EXIT_CODE,
+    BLOCK_DECISION,
+    BLOCK_REASON_PREFIX,
+    BLOCK_REASON_SUFFIX,
+    CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE,
+    CLAUDE_HOME_DIRECTORY_NAME,
+    CURSOR_COMPLETED_STATUS,
+    CURSOR_CONVERSATION_ID_KEY,
+    CURSOR_FOLLOWUP_LIMIT,
+    CURSOR_FOLLOWUP_MESSAGE_KEY,
+    CURSOR_LOOP_COUNT_KEY,
+    CURSOR_STATUS_KEY,
+    DECISION_KEY,
+    HOOK_EVENT_NAME,
+    INCOMPLETE_STATUSES,
+    ITEM_LINE_TEMPLATE,
+    LAST_ASSISTANT_MESSAGE_KEY,
+    REASON_KEY,
+    REPORT_LINE_PATTERN,
+    REPORTED_TEXT_GROUP_INDEX,
+    SESSION_ID_KEY,
+    TASK_FILE_GLOB,
+    TASK_ID_KEY,
+    TASK_LIST_ID_ENVIRONMENT_VARIABLE,
+    TASK_NUMBER_REFERENCE_TEMPLATE,
+    TASK_STATUS_KEY,
+    TASK_SUBJECT_KEY,
+    TASKS_DIRECTORY_NAME,
+    TRANSCRIPT_PATH_KEY,
+    UTF8_ENCODING,
+    WORD_BOUNDARY_PATTERN,
+    WORD_SEPARATOR,
+)
+
+
+def _claude_home() -> Path:
+    configured_directory = os.environ.get(CLAUDE_CONFIG_DIRECTORY_ENVIRONMENT_VARIABLE)
+    if configured_directory:
+        return Path(configured_directory)
+    return Path.home() / CLAUDE_HOME_DIRECTORY_NAME
+
+
+def _task_file_item(task_file: Path) -> TaskItem | None:
+    try:
+        task_text = task_file.read_text(encoding=UTF8_ENCODING)
+    except OSError:
+        return None
+    all_task_fields = parsed_object(task_text)
+    if all_task_fields is None:
+        return None
+    return TaskItem(
+        str(all_task_fields.get(TASK_ID_KEY, task_file.stem)),
+        str(all_task_fields.get(TASK_SUBJECT_KEY, "")),
+        str(all_task_fields.get(TASK_STATUS_KEY, "")),
+    )
+
+
+def task_store_items(session_id: object) -> list[TaskItem] | None:
+    """Return the task store items for the session, or None when no store exists."""
+    task_list_id = os.environ.get(TASK_LIST_ID_ENVIRONMENT_VARIABLE) or session_id
+    if not isinstance(task_list_id, str) or not task_list_id:
+        return None
+    task_directory = _claude_home() / TASKS_DIRECTORY_NAME / task_list_id
+    if not task_directory.is_dir():
+        return None
+    all_items = (_task_file_item(each_file) for each_file in sorted(task_directory.glob(TASK_FILE_GLOB)))
+    return [each_item for each_item in all_items if each_item is not None]
+
+
+def _normalized(text: str) -> str:
+    return WORD_SEPARATOR.join(text.lower().split())
+
+
+def _reported_texts(reply_text: str) -> list[str]:
+    all_matches = (re.match(REPORT_LINE_PATTERN, each_line, re.IGNORECASE) for each_line in reply_text.splitlines())
+    return [_normalized(each_match.group(REPORTED_TEXT_GROUP_INDEX)) for each_match in all_matches if each_match]
+
+
+def is_reported(task_item: TaskItem, reply_text: str) -> bool:
+    """Return True when a Blocked: or Open: line of the reply names the item."""
+    subject_text = _normalized(task_item.subject)
+    number_pattern = re.escape(TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=task_item.item_id)) + WORD_BOUNDARY_PATTERN
+    return any(
+        (subject_text and subject_text in each_text) or re.search(number_pattern, each_text)
+        for each_text in _reported_texts(reply_text)
+    )
+
+
+def unreported_open_items(all_hook_input_fields: dict[str, object]) -> list[TaskItem]:
+    """Return the open task items the closing reply does not report."""
+    replay = replayed_transcript(all_hook_input_fields.get(TRANSCRIPT_PATH_KEY))
+    all_items = task_store_items(all_hook_input_fields.get(SESSION_ID_KEY))
+    if all_items is None:
+        all_items = replay.items() or []
+    reply_value = all_hook_input_fields.get(LAST_ASSISTANT_MESSAGE_KEY)
+    reply_text = reply_value if isinstance(reply_value, str) else replay.last_assistant_text
+    return [
+        each_item
+        for each_item in all_items
+        if each_item.status in INCOMPLETE_STATUSES and not is_reported(each_item, reply_text)
+    ]
+
+
+def block_reason_for(all_open_items: list[TaskItem]) -> str:
+    """Return the block reason that lists each open item."""
+    all_item_lines = (
+        ITEM_LINE_TEMPLATE.format(subject=each_item.subject or TASK_NUMBER_REFERENCE_TEMPLATE.format(task_id=each_item.item_id))
+        for each_item in all_open_items
+    )
+    return BLOCK_REASON_PREFIX + "".join(all_item_lines) + BLOCK_REASON_SUFFIX
+
+
+def block_output_for(all_hook_input_fields: dict[str, object], block_reason: str) -> dict[str, str]:
+    """Return the block output; a Cursor payload also gets the reason as ``followup_message``."""
+    block_output = {DECISION_KEY: BLOCK_DECISION, REASON_KEY: block_reason}
+    if all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY):
+        block_output[CURSOR_FOLLOWUP_MESSAGE_KEY] = block_reason
+    return block_output
+
+
+def is_unfinished_cursor_stop(all_hook_input_fields: dict[str, object]) -> bool:
+    """Return True for a Cursor stop whose run was aborted or ended in an error."""
+    if not all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY):
+        return False
+    stop_status = all_hook_input_fields.get(CURSOR_STATUS_KEY)
+    return stop_status is not None and stop_status != CURSOR_COMPLETED_STATUS
+
+
+def has_spent_cursor_followups(all_hook_input_fields: dict[str, object]) -> bool:
+    """Return True for a Cursor stop that already sent the follow-up limit.
+
+    Cursor caps native stop follow-ups at five per script, but a copy it imports
+    from ``~/.claude/settings.json`` has no cap, so the gate stops at five itself.
+    """
+    if not all_hook_input_fields.get(CURSOR_CONVERSATION_ID_KEY):
+        return False
+    loop_count = all_hook_input_fields.get(CURSOR_LOOP_COUNT_KEY)
+    return isinstance(loop_count, int) and loop_count >= CURSOR_FOLLOWUP_LIMIT
+
+
+def main() -> int:
+    hook_input = read_hook_input_dictionary_from_stdin()
+    if hook_input is None or is_unfinished_cursor_stop(hook_input) or has_spent_cursor_followups(hook_input):
+        return ALLOW_EXIT_CODE
+    all_open_items = unreported_open_items(hook_input)
+    if not all_open_items:
+        return ALLOW_EXIT_CODE
+    block_reason = block_reason_for(all_open_items)
+    reply_value = hook_input.get(LAST_ASSISTANT_MESSAGE_KEY)
+    log_hook_block(
+        Path(__file__).name,
+        HOOK_EVENT_NAME,
+        block_reason,
+        offending_input_preview=reply_value if isinstance(reply_value, str) else None,
+    )
+    sys.stdout.write(json.dumps(block_output_for(hook_input, block_reason)))
+    return ALLOW_EXIT_CODE
+
+
+if __name__ == "__main__":
+    sys.exit(main())