claude-dev-env 8.87.1 → 8.88.1

package/AGENTS.md

@@ -4,6 +4,7 @@ Every rule below is always on. A rule with a link keeps its full text in that fi
 - **Diffs.** Show the hunk. No prose stand-in.
 - **Verdicts.** One line. Read files first. Quote file:line. Code beats brief. No flip-flops.
 - **Evidence** ([`~/.claude/docs/agents-guidance/evidence.md`](docs/agents-guidance/evidence.md)). Act and state only on what you or your workers saw, ran, or tested. Settle an open fact with a tool before you answer. When no permitted tool reaches it, name the check and who can run it.
+- **Asks** ([`~/.claude/docs/agents-guidance/asks.md`](docs/agents-guidance/asks.md)). Work every ask from the user now, without pause, until it is done with proof you saw or blocked on something only the user can give. No deadlines and no "later". Each ask is a task list item. A turn ends only when every item is completed, or the reply ends with `Blocked: <item> - <what the user must give>` or `Open: <item> - <the step you take next>` for it. The Stop hook `open_tasks_stop_gate.py` holds the turn until then.
 - **Writes.** Write/Edit only. LF. After: git diff --check, file <path>. ASCII unless the file already isn't.
 - **Edit gate.** Own worktree. Path overlap with another session → stop. Behind origin/main → rebase or report.
 - **Scope.** Min diff. No drive-by reformat. No blanket autofix without tests and revert on break.

package/bin/cursor-agents-guidance.mjs

@@ -0,0 +1,94 @@
+import { join } from 'node:path';
+
+import {
+    CURSOR_GUIDANCE_HOOK_RELATIVE_PATH,
+    CURSOR_HOOK_TIMEOUT_SECONDS,
+    CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH,
+    CURSOR_SESSION_START_EVENT,
+    CURSOR_STOP_EVENT,
+} from './install-constants.mjs';
+import { updateCursorHooksFile, withOwnedCursorHooks, withoutOwnedCursorHooks } from './cursor-native-hooks.mjs';
+
+const DEFAULT_PYTHON_COMMAND = 'python3';
+const OWNED_SCRIPT_NAMES = [
+    CURSOR_GUIDANCE_HOOK_RELATIVE_PATH.at(-1),
+    CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH.at(-1),
+];
+
+function quotedPath(pathValue) {
+    return `'${pathValue.replaceAll("'", "'\\''")}'`;
+}
+
+/**
+ * True for a Cursor hook command this module owns.
+ *
+ * @param {string} forwardSlashedCommand A hook command with forward slashes.
+ * @returns {boolean} True when the command runs the guidance hook or the open tasks gate.
+ */
+export function isAgentsGuidanceCommand(forwardSlashedCommand) {
+    return OWNED_SCRIPT_NAMES.some(eachName => forwardSlashedCommand.includes(eachName));
+}
+
+/**
+ * Return the Cursor hooks configuration, in native format, without the agents guidance hooks.
+ *
+ * @param {object} configuration The parsed ~/.cursor/hooks.json.
+ * @returns {object} The configuration with both owned entries removed.
+ */
+export function withoutCursorAgentsGuidanceHooks(configuration) {
+    return withoutOwnedCursorHooks(configuration, isAgentsGuidanceCommand);
+}
+
+/**
+ * Return the Cursor hooks configuration with one guidance `sessionStart` entry and one open tasks `stop` entry.
+ *
+ * The `sessionStart` hook returns the installed AGENTS.md as `additional_context`,
+ * which Cursor adds to the session's context. The `stop` hook runs the open
+ * tasks gate, whose `followup_message` Cursor submits as the next user message.
+ *
+ * @param {object} configuration The parsed ~/.cursor/hooks.json.
+ * @param {{guidanceCommand: string, openTasksCommand: string}} commands The two hook commands.
+ * @returns {object} The merged native configuration.
+ */
+export function mergeCursorAgentsGuidanceHooks(configuration, commands) {
+    return withOwnedCursorHooks(configuration, isAgentsGuidanceCommand, {
+        [CURSOR_SESSION_START_EVENT]: [{ command: commands.guidanceCommand, timeout: CURSOR_HOOK_TIMEOUT_SECONDS }],
+        [CURSOR_STOP_EVENT]: [{ command: commands.openTasksCommand, timeout: CURSOR_HOOK_TIMEOUT_SECONDS }],
+    });
+}
+
+/**
+ * Register the agents guidance and open tasks hooks in the Cursor home.
+ *
+ * The commands use the interpreter the installer detected, the same one the
+ * Claude and Codex hooks use, so a Windows install runs the resolved
+ * `python.exe` path and not the Microsoft Store `python3` stub.
+ *
+ * @param {{cursorDirectory: string, hooksDirectory: string, guidancePath: string, pythonCommand?: string, formatPathArgument?: (pathValue: string) => string}} options Install paths, the detected interpreter, and the platform path quoting.
+ * @returns {string|null} The hooks.json path when this run changed it.
+ */
+export function writeCursorAgentsGuidanceHooks(options) {
+    const pythonCommand = options.pythonCommand ?? DEFAULT_PYTHON_COMMAND;
+    const formatPathArgument = options.formatPathArgument ?? quotedPath;
+    const guidanceScript = join(options.hooksDirectory, ...CURSOR_GUIDANCE_HOOK_RELATIVE_PATH);
+    const openTasksScript = join(options.hooksDirectory, ...CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH);
+    const commands = {
+        guidanceCommand: `${pythonCommand} ${formatPathArgument(guidanceScript)} ${formatPathArgument(options.guidancePath)}`,
+        openTasksCommand: `${pythonCommand} ${formatPathArgument(openTasksScript)}`,
+    };
+    return updateCursorHooksFile(
+        options.cursorDirectory,
+        configuration => mergeCursorAgentsGuidanceHooks(configuration, commands),
+        { createWhenMissing: true },
+    );
+}
+
+/**
+ * Remove the agents guidance and open tasks hooks from the Cursor home.
+ *
+ * @param {string} cursorDirectory The Cursor home.
+ * @returns {string|null} The hooks.json path when this run changed it.
+ */
+export function removeCursorAgentsGuidanceHooks(cursorDirectory) {
+    return updateCursorHooksFile(cursorDirectory, withoutCursorAgentsGuidanceHooks);
+}

package/bin/cursor-agents-guidance.test.mjs

@@ -0,0 +1,94 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+    mergeCursorAgentsGuidanceHooks,
+    removeCursorAgentsGuidanceHooks,
+    writeCursorAgentsGuidanceHooks,
+} from './cursor-agents-guidance.mjs';
+
+const USER_SESSION_ENTRY = { command: './user-session.sh' };
+const LEGACY_GUIDANCE_GROUP = {
+    matcher: 'startup|resume|clear|compact',
+    hooks: [{ type: 'command', command: "python3 '/home/dev/.agents/hooks/session/cursor_agents_guidance.py' AGENTS.md", timeout: 10 }],
+};
+const LEGACY_GATE_GROUP = {
+    matcher: '',
+    hooks: [{ type: 'command', command: "python3 '/home/dev/.agents/hooks/blocking/open_tasks_stop_gate.py'", timeout: 10 }],
+};
+
+test('merge adds one native sessionStart entry and one native stop entry and keeps user entries', () => {
+    const commands = { guidanceCommand: 'python3 cursor_agents_guidance.py AGENTS.md', openTasksCommand: 'python3 open_tasks_stop_gate.py' };
+    const once = mergeCursorAgentsGuidanceHooks({ hooks: { sessionStart: [USER_SESSION_ENTRY] } }, commands);
+    assert.deepEqual(mergeCursorAgentsGuidanceHooks(once, commands), once);
+    assert.deepEqual(once, {
+        version: 1,
+        hooks: {
+            sessionStart: [USER_SESSION_ENTRY, { command: commands.guidanceCommand, timeout: 10 }],
+            stop: [{ command: commands.openTasksCommand, timeout: 10 }],
+        },
+    });
+});
+
+test('merge replaces the Claude-style groups an earlier build of this module wrote', () => {
+    const commands = { guidanceCommand: 'py cursor_agents_guidance.py AGENTS.md', openTasksCommand: 'py open_tasks_stop_gate.py' };
+    const merged = mergeCursorAgentsGuidanceHooks(
+        { hooks: { SessionStart: [LEGACY_GUIDANCE_GROUP], Stop: [LEGACY_GATE_GROUP] } },
+        commands,
+    );
+    assert.deepEqual(Object.keys(merged.hooks), ['sessionStart', 'stop']);
+    assert.equal(merged.hooks.sessionStart.length, 1);
+    assert.equal(merged.hooks.stop.length, 1);
+    assert.equal(merged.hooks.stop[0].command, commands.openTasksCommand);
+});
+
+test('write registers both hooks with the installed paths and remove takes out exactly those', () => {
+    const cursorDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-guidance-'));
+    try {
+        const hooksPath = join(cursorDirectory, 'hooks.json');
+        writeFileSync(hooksPath, JSON.stringify({ version: 1, hooks: { sessionStart: [USER_SESSION_ENTRY] } }));
+        const installOptions = {
+            cursorDirectory,
+            hooksDirectory: '/home/dev/.agents/hooks',
+            guidancePath: '/home/dev/.agents/AGENTS.md',
+        };
+        assert.equal(writeCursorAgentsGuidanceHooks(installOptions), hooksPath);
+        const written = JSON.parse(readFileSync(hooksPath, 'utf8'));
+        const guidanceScript = join(installOptions.hooksDirectory, 'session', 'cursor_agents_guidance.py');
+        const openTasksScript = join(installOptions.hooksDirectory, 'blocking', 'open_tasks_stop_gate.py');
+        assert.equal(
+            written.hooks.sessionStart[1].command,
+            `python3 '${guidanceScript}' '/home/dev/.agents/AGENTS.md'`,
+        );
+        assert.equal(written.hooks.stop[0].command, `python3 '${openTasksScript}'`);
+        assert.equal(writeCursorAgentsGuidanceHooks(installOptions), null);
+        removeCursorAgentsGuidanceHooks(cursorDirectory);
+        assert.deepEqual(JSON.parse(readFileSync(hooksPath, 'utf8')), { version: 1, hooks: { sessionStart: [USER_SESSION_ENTRY] } });
+    } finally {
+        rmSync(cursorDirectory, { recursive: true, force: true });
+    }
+});
+
+test('write uses the detected interpreter and platform path quoting and sets the schema version', () => {
+    const cursorDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-guidance-'));
+    try {
+        const hooksDirectory = 'C:/Users/dev/.agents/hooks';
+        writeCursorAgentsGuidanceHooks({
+            cursorDirectory,
+            hooksDirectory,
+            guidancePath: 'C:/Users/dev/.agents/AGENTS.md',
+            pythonCommand: 'C:/Python312/python.exe',
+            formatPathArgument: pathValue => `"${pathValue}"`,
+        });
+        const written = JSON.parse(readFileSync(join(cursorDirectory, 'hooks.json'), 'utf8'));
+        assert.equal(written.version, 1);
+        const openTasksScript = join(hooksDirectory, 'blocking', 'open_tasks_stop_gate.py');
+        assert.equal(written.hooks.stop[0].command, `C:/Python312/python.exe "${openTasksScript}"`);
+        assert.match(written.hooks.sessionStart[0].command, /^C:\/Python312\/python\.exe "/);
+    } finally {
+        rmSync(cursorDirectory, { recursive: true, force: true });
+    }
+});

package/bin/cursor-native-hooks.mjs

@@ -0,0 +1,128 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+    ALL_CURSOR_LIFECYCLE_EVENT_NAMES,
+    CURSOR_HOOKS_FILE_NAME,
+    CURSOR_HOOKS_SCHEMA_VERSION,
+    CURSOR_NATIVE_EVENT_NAME_BY_LEGACY_NAME,
+} from './install-constants.mjs';
+
+/**
+ * Cursor reads ~/.cursor/hooks.json only in its own format: `version: 1` and a
+ * `hooks` map from a camelCase event (`sessionStart`, `beforeSubmitPrompt`,
+ * `stop`) to flat `{command, timeout}` entries. A Claude-style group entry
+ * (`{"matcher": ..., "hooks": [...]}`) never runs, and while one is in the
+ * file Cursor runs none of the file's hooks. This module turns such groups
+ * into native entries and lets each package module replace only the entries
+ * it owns.
+ */
+
+function isLegacyGroupEntry(entry) {
+    return Boolean(entry) && typeof entry === 'object' && Array.isArray(entry.hooks) && typeof entry.command !== 'string';
+}
+
+function nativeEntriesFromLegacyGroup(group, nativeEventName) {
+    const keepsMatcher = typeof group.matcher === 'string'
+        && group.matcher !== ''
+        && group.matcher !== '*'
+        && !ALL_CURSOR_LIFECYCLE_EVENT_NAMES.has(nativeEventName);
+    return group.hooks
+        .filter(eachHook => eachHook && typeof eachHook.command === 'string')
+        .map(eachHook => ({
+            command: eachHook.command,
+            ...(typeof eachHook.timeout === 'number' ? { timeout: eachHook.timeout } : {}),
+            ...(keepsMatcher ? { matcher: group.matcher } : {}),
+        }));
+}
+
+/**
+ * Return the configuration in Cursor's native format.
+ *
+ * Every Claude-style group becomes one flat entry per inner command, under the
+ * native event name (`SessionStart` -> `sessionStart`, `UserPromptSubmit` ->
+ * `beforeSubmitPrompt`, `Stop` -> `stop`). Native entries are kept as they are.
+ *
+ * @param {object} configuration A parsed Cursor hooks file.
+ * @returns {object} The configuration with `version` set and only native entries.
+ */
+export function nativeCursorHooksConfiguration(configuration) {
+    const { version, hooks, ...otherFields } = configuration && typeof configuration === 'object' ? configuration : {};
+    const allHooksByEvent = hooks && typeof hooks === 'object' ? hooks : {};
+    const nativeHooks = {};
+    for (const [eventName, allEntries] of Object.entries(allHooksByEvent)) {
+        const nativeEventName = CURSOR_NATIVE_EVENT_NAME_BY_LEGACY_NAME[eventName] ?? eventName;
+        if (!Array.isArray(allEntries)) {
+            nativeHooks[nativeEventName] = allEntries;
+            continue;
+        }
+        const nativeEntries = allEntries.flatMap(eachEntry => (
+            isLegacyGroupEntry(eachEntry) ? nativeEntriesFromLegacyGroup(eachEntry, nativeEventName) : [eachEntry]
+        ));
+        nativeHooks[nativeEventName] = [...(nativeHooks[nativeEventName] ?? []), ...nativeEntries];
+    }
+    return { version: version ?? CURSOR_HOOKS_SCHEMA_VERSION, ...otherFields, hooks: nativeHooks };
+}
+
+function commandOf(entry) {
+    return entry && typeof entry.command === 'string' ? entry.command.replace(/\\/g, '/') : '';
+}
+
+/**
+ * Return the native configuration without the entries one package module owns.
+ *
+ * @param {object} configuration A parsed Cursor hooks file.
+ * @param {(forwardSlashedCommand: string) => boolean} isOwnedCommand True for a command the caller owns.
+ * @returns {object} The native configuration; an event left empty by the removal is dropped.
+ */
+export function withoutOwnedCursorHooks(configuration, isOwnedCommand) {
+    const nativeConfiguration = nativeCursorHooksConfiguration(configuration);
+    const keptHooks = {};
+    for (const [eventName, allEntries] of Object.entries(nativeConfiguration.hooks)) {
+        if (!Array.isArray(allEntries)) {
+            keptHooks[eventName] = allEntries;
+            continue;
+        }
+        const keptEntries = allEntries.filter(eachEntry => !isOwnedCommand(commandOf(eachEntry)));
+        if (keptEntries.length > 0 || allEntries.length === 0) keptHooks[eventName] = keptEntries;
+    }
+    return { ...nativeConfiguration, hooks: keptHooks };
+}
+
+/**
+ * Return the native configuration with exactly one copy of the caller's entries.
+ *
+ * @param {object} configuration A parsed Cursor hooks file.
+ * @param {(forwardSlashedCommand: string) => boolean} isOwnedCommand True for a command the caller owns.
+ * @param {Record<string, object[]>} allEntriesByEvent The caller's entries per native event.
+ * @returns {object} The merged native configuration.
+ */
+export function withOwnedCursorHooks(configuration, isOwnedCommand, allEntriesByEvent) {
+    const cleaned = withoutOwnedCursorHooks(configuration, isOwnedCommand);
+    const mergedHooks = { ...cleaned.hooks };
+    for (const [eventName, allEntries] of Object.entries(allEntriesByEvent)) {
+        mergedHooks[eventName] = [...(Array.isArray(mergedHooks[eventName]) ? mergedHooks[eventName] : []), ...allEntries];
+    }
+    return { ...cleaned, hooks: mergedHooks };
+}
+
+/**
+ * Apply one transform to `<cursorDirectory>/hooks.json` and write it when the text changes.
+ *
+ * @param {string} cursorDirectory The Cursor home.
+ * @param {(configuration: object) => object} transform Maps the parsed file to the new one.
+ * @param {{createWhenMissing?: boolean}} [options] Whether a missing file is created.
+ * @returns {string|null} The hooks.json path when this call changed it.
+ */
+export function updateCursorHooksFile(cursorDirectory, transform, options = {}) {
+    const hooksPath = join(cursorDirectory, CURSOR_HOOKS_FILE_NAME);
+    const fileExists = existsSync(hooksPath);
+    if (!fileExists && !options.createWhenMissing) return null;
+    const currentText = fileExists ? readFileSync(hooksPath, 'utf8') : null;
+    const current = currentText === null ? {} : JSON.parse(currentText.replace(/^\uFEFF/, ''));
+    const updatedText = `${JSON.stringify(transform(current), null, 2)}\n`;
+    if (updatedText === currentText) return null;
+    mkdirSync(cursorDirectory, { recursive: true });
+    writeFileSync(hooksPath, updatedText);
+    return hooksPath;
+}

package/bin/cursor-native-hooks.test.mjs

@@ -0,0 +1,78 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import {
+    nativeCursorHooksConfiguration,
+    updateCursorHooksFile,
+    withOwnedCursorHooks,
+    withoutOwnedCursorHooks,
+} from './cursor-native-hooks.mjs';
+
+const LEGACY_SESSION_GROUP = {
+    matcher: 'startup|resume|clear|compact',
+    hooks: [{ type: 'command', command: "'C:\\Users\\dev\\.cursor\\plugins\\deepstack\\hooks\\session-start.sh' cursor" }],
+};
+const LEGACY_PROMPT_GROUP = {
+    matcher: '',
+    hooks: [{ type: 'command', command: 'python3 /home/dev/.agents/hooks/session/deepen_first_prompt.py', timeout: 10 }],
+};
+const USER_TOOL_GROUP = { matcher: 'Shell', hooks: [{ type: 'command', command: './audit.sh' }] };
+const isOwned = command => command.includes('plugins/deepstack/hooks/session-start.') || command.includes('deepen_first_prompt.py');
+
+test('Claude-style groups become flat native entries under the Cursor event names', () => {
+    const native = nativeCursorHooksConfiguration({
+        hooks: { SessionStart: [LEGACY_SESSION_GROUP], UserPromptSubmit: [LEGACY_PROMPT_GROUP], PreToolUse: [USER_TOOL_GROUP] },
+    });
+    assert.deepEqual(native, {
+        version: 1,
+        hooks: {
+            sessionStart: [{ command: LEGACY_SESSION_GROUP.hooks[0].command }],
+            beforeSubmitPrompt: [{ command: LEGACY_PROMPT_GROUP.hooks[0].command, timeout: 10 }],
+            preToolUse: [{ command: './audit.sh', matcher: 'Shell' }],
+        },
+    });
+    assert.equal(JSON.stringify(native).includes('"hooks":[{"type"'), false);
+});
+
+test('native entries and other fields stay, and the result is stable', () => {
+    const configuration = { version: 1, note: 'keep', hooks: { stop: [{ command: './audit.sh', loop_limit: 3 }] } };
+    assert.deepEqual(nativeCursorHooksConfiguration(configuration), configuration);
+    assert.deepEqual(nativeCursorHooksConfiguration(nativeCursorHooksConfiguration(configuration)), configuration);
+});
+
+test('owned entries collapse to one copy and removal drops only owned entries', () => {
+    const legacyFile = {
+        version: 1,
+        hooks: {
+            SessionStart: [LEGACY_SESSION_GROUP, LEGACY_SESSION_GROUP, LEGACY_SESSION_GROUP],
+            UserPromptSubmit: [LEGACY_PROMPT_GROUP],
+            stop: [{ command: './user-stop.sh' }],
+        },
+    };
+    const ownedEntries = {
+        sessionStart: [{ command: "'/home/dev/.cursor/plugins/deepstack/hooks/session-start.sh' cursor", timeout: 10 }],
+        beforeSubmitPrompt: [{ command: 'python3 /home/dev/.agents/hooks/session/deepen_first_prompt.py', timeout: 10 }],
+    };
+    const merged = withOwnedCursorHooks(legacyFile, isOwned, ownedEntries);
+    assert.deepEqual(merged.hooks, { ...ownedEntries, stop: [{ command: './user-stop.sh' }] });
+    assert.deepEqual(withOwnedCursorHooks(merged, isOwned, ownedEntries), merged);
+    assert.deepEqual(withoutOwnedCursorHooks(merged, isOwned), { version: 1, hooks: { stop: [{ command: './user-stop.sh' }] } });
+});
+
+test('the file update writes only on change, strips a BOM, and creates a file only when asked', () => {
+    const cursorDirectory = mkdtempSync(join(tmpdir(), 'cdev-cursor-native-'));
+    try {
+        assert.equal(updateCursorHooksFile(cursorDirectory, configuration => configuration), null);
+        const hooksPath = updateCursorHooksFile(cursorDirectory, nativeCursorHooksConfiguration, { createWhenMissing: true });
+        assert.deepEqual(JSON.parse(readFileSync(hooksPath, 'utf8')), { version: 1, hooks: {} });
+        writeFileSync(hooksPath, `\uFEFF${JSON.stringify({ hooks: { Stop: [LEGACY_PROMPT_GROUP] } })}`);
+        updateCursorHooksFile(cursorDirectory, nativeCursorHooksConfiguration);
+        assert.equal(JSON.parse(readFileSync(hooksPath, 'utf8')).hooks.stop.length, 1);
+        assert.equal(updateCursorHooksFile(cursorDirectory, nativeCursorHooksConfiguration), null);
+    } finally {
+        rmSync(cursorDirectory, { recursive: true, force: true });
+    }
+});

package/bin/install-constants.mjs

@@ -179,3 +179,32 @@ export const ALL_CODEX_NATIVE_PRE_TOOL_USE_MATCHERS = new Set([
     CODEX_NATIVE_ROUTING_MATCHER,
     CODEX_SUBAGENT_PROMPT_MATCHER,
 ]);
+export const ALL_CODEX_NATIVE_STOP_HOOK_SCRIPT_NAMES = new Set([
+    'open_tasks_stop_gate.py',
+]);
+export const CURSOR_HOOKS_FILE_NAME = 'hooks.json';
+export const CURSOR_HOOKS_SCHEMA_VERSION = 1;
+export const CURSOR_HOOK_TIMEOUT_SECONDS = 10;
+export const CURSOR_GUIDANCE_HOOK_RELATIVE_PATH = Object.freeze(['session', 'cursor_agents_guidance.py']);
+export const CURSOR_OPEN_TASKS_HOOK_RELATIVE_PATH = Object.freeze(['blocking', 'open_tasks_stop_gate.py']);
+export const CURSOR_SESSION_START_EVENT = 'sessionStart';
+export const CURSOR_BEFORE_SUBMIT_PROMPT_EVENT = 'beforeSubmitPrompt';
+export const CURSOR_STOP_EVENT = 'stop';
+export const CURSOR_NATIVE_EVENT_NAME_BY_LEGACY_NAME = Object.freeze({
+    SessionStart: CURSOR_SESSION_START_EVENT,
+    SessionEnd: 'sessionEnd',
+    UserPromptSubmit: CURSOR_BEFORE_SUBMIT_PROMPT_EVENT,
+    Stop: CURSOR_STOP_EVENT,
+    SubagentStop: 'subagentStop',
+    PreToolUse: 'preToolUse',
+    PostToolUse: 'postToolUse',
+    PreCompact: 'preCompact',
+});
+export const ALL_CURSOR_LIFECYCLE_EVENT_NAMES = new Set([
+    CURSOR_SESSION_START_EVENT,
+    'sessionEnd',
+    CURSOR_BEFORE_SUBMIT_PROMPT_EVENT,
+    CURSOR_STOP_EVENT,
+    'subagentStop',
+    'preCompact',
+]);

package/bin/install-deepstack-plugin.mjs

@@ -1,5 +1,5 @@
 import { spawnSync } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import {
@@ -7,6 +7,12 @@ import {
     marketplacePluginsPlan,
     shouldInstallMarketplacePlugin,
 } from './install-pstack-plugin.mjs';
+import {
+    CURSOR_BEFORE_SUBMIT_PROMPT_EVENT,
+    CURSOR_HOOK_TIMEOUT_SECONDS,
+    CURSOR_SESSION_START_EVENT,
+} from './install-constants.mjs';
+import { updateCursorHooksFile, withOwnedCursorHooks, withoutOwnedCursorHooks } from './cursor-native-hooks.mjs';
 
 export const DEEPSTACK_MARKETPLACE_REPOSITORY = 'jl-cmd-projects/DeepStack';
 export const DEEPSTACK_MARKETPLACE_NAME = 'DeepStack';
@@ -19,7 +25,11 @@ export const DEEPSTACK_SOURCE_VARIABLE = 'CDE_DEEPSTACK_SOURCE';
 export const DEEPSTACK_CURSOR_DIRECTORY_NAME = 'plugins/deepstack';
 export const DEEPSTACK_SKILL_RELATIVE_PATH = 'skills/deepstack-mode/SKILL.md';
 export const DEEPSTACK_SESSION_SCRIPT_RELATIVE_PATH = 'hooks/session-start.sh';
+export const DEEPSTACK_SESSION_POWERSHELL_RELATIVE_PATH = 'hooks/session-start.ps1';
+export const DEEPSTACK_CURSOR_SESSION_COMMAND_MARKER = 'plugins/deepstack/hooks/session-start.';
 export const DEEPSTACK_SESSION_RUNTIME = 'cursor';
+const WINDOWS_POWERSHELL_FILE_PREFIX = 'powershell -NoProfile -ExecutionPolicy Bypass -File';
+const DEFAULT_PYTHON_COMMAND = 'python3';
 export const DEEPSTACK_FIRST_TASK_HOOK_NAME = 'deepen_first_prompt.py';
 export const DEEPSTACK_CODEX_MODEL_SHEET_NAME = 'deepstack-models.md';
 
@@ -49,7 +59,7 @@ function quoteCommandPath(pathValue) {
  * Read the Claude, Codex, and Cursor actions one DeepStack install performs.
  *
  * Claude and Codex use the marketplace verbs. Cursor has no plugin command, so
- * its action is a copy into the Cursor home plus two hook registrations.
+ * its action is a copy into the Cursor home plus two native hook registrations.
  *
  * @returns {{claude: object, codex: object, cursor: {
  *   pluginDirectoryName: string,
@@ -127,48 +137,76 @@ export function resolveDeepStackPluginSource(options = {}) {
 }
 
 /**
- * Add the SessionStart and first-task hook groups when they are absent.
+ * True for a Cursor hook command the DeepStack install owns.
+ *
+ * @param {string} forwardSlashedCommand A hook command with forward slashes.
+ * @returns {boolean} True for the DeepStack session hook or the first-task hook.
+ */
+export function isDeepStackCursorCommand(forwardSlashedCommand) {
+    return forwardSlashedCommand.includes(DEEPSTACK_CURSOR_SESSION_COMMAND_MARKER)
+        || forwardSlashedCommand.includes(DEEPSTACK_FIRST_TASK_HOOK_NAME);
+}
+
+/**
+ * Return the native Cursor configuration with one DeepStack session entry and one first-task entry.
+ *
+ * Earlier installs wrote these as Claude-style groups, which Cursor never ran;
+ * every owned copy, old or new, is replaced by one native entry each.
  *
  * @param {object} configuration The parsed Cursor hooks file.
  * @param {{sessionCommand: string, firstTaskCommand: string}} commands The two commands.
- * @returns {object} The configuration with both groups present.
+ * @returns {object} The configuration with both native entries present once.
  */
 export function mergeDeepStackCursorHooks(configuration, commands) {
-    const hooks = configuration.hooks && typeof configuration.hooks === 'object'
-        ? configuration.hooks
-        : {};
-    const sessionGroups = Array.isArray(hooks.SessionStart) ? [...hooks.SessionStart] : [];
-    const promptGroups = Array.isArray(hooks.UserPromptSubmit) ? [...hooks.UserPromptSubmit] : [];
-    const listed = (groups, needle) => JSON.stringify(groups).includes(needle);
-    if (!listed(sessionGroups, DEEPSTACK_SESSION_SCRIPT_RELATIVE_PATH)) {
-        sessionGroups.push({
-            matcher: 'startup|resume|clear|compact',
-            hooks: [{ type: 'command', command: commands.sessionCommand }],
-        });
-    }
-    if (!listed(promptGroups, DEEPSTACK_FIRST_TASK_HOOK_NAME)) {
-        promptGroups.push({
-            matcher: '',
-            hooks: [{ type: 'command', command: commands.firstTaskCommand, timeout: 10 }],
-        });
+    return withOwnedCursorHooks(configuration, isDeepStackCursorCommand, {
+        [CURSOR_SESSION_START_EVENT]: [{ command: commands.sessionCommand, timeout: CURSOR_HOOK_TIMEOUT_SECONDS }],
+        [CURSOR_BEFORE_SUBMIT_PROMPT_EVENT]: [{ command: commands.firstTaskCommand, timeout: CURSOR_HOOK_TIMEOUT_SECONDS }],
+    });
+}
+
+/**
+ * Remove the DeepStack session and first-task entries from the Cursor hooks file.
+ *
+ * @param {string} cursorDirectory The Cursor home.
+ * @returns {string|null} The hooks.json path when this call changed it.
+ */
+export function removeDeepStackCursorHooks(cursorDirectory) {
+    return updateCursorHooksFile(
+        cursorDirectory,
+        configuration => withoutOwnedCursorHooks(configuration, isDeepStackCursorCommand),
+    );
+}
+
+/**
+ * Build the Cursor command for the DeepStack session script.
+ *
+ * Cursor runs hook commands through PowerShell on Windows, where a `.sh` path
+ * does not run, so Windows uses the plugin's `session-start.ps1`.
+ *
+ * @param {string} pluginDirectory The plugin copy in the Cursor home.
+ * @param {(pathValue: string) => string} formatPathArgument The platform path quoting.
+ * @param {string} platform The Node platform name.
+ * @returns {string} The session command.
+ */
+export function deepStackCursorSessionCommand(pluginDirectory, formatPathArgument, platform) {
+    const plan = deepStackInstallPlan().cursor;
+    const powerShellScript = join(pluginDirectory, DEEPSTACK_SESSION_POWERSHELL_RELATIVE_PATH);
+    if (platform === 'win32' && existsSync(powerShellScript)) {
+        return `${WINDOWS_POWERSHELL_FILE_PREFIX} ${formatPathArgument(powerShellScript)} ${plan.sessionRuntimeArgument}`;
     }
-    return {
-        ...configuration,
-        hooks: {
-            ...hooks,
-            SessionStart: sessionGroups,
-            UserPromptSubmit: promptGroups,
-        },
-    };
+    return `${formatPathArgument(join(pluginDirectory, plan.sessionScriptRelativePath))} ${plan.sessionRuntimeArgument}`;
 }
 
 /**
- * Copy the plugin into the Cursor home and register both hooks.
+ * Copy the plugin into the Cursor home and register both hooks in Cursor's native format.
  *
  * @param {object} options Copy inputs.
  * @param {string} options.cursorDirectory The Cursor home, usually ~/.cursor.
  * @param {string|null} options.pluginSourceDirectory The plugin tree to copy.
  * @param {string} options.firstTaskHookPath Absolute path of deepen_first_prompt.py.
+ * @param {string} [options.pythonCommand] The interpreter the installer detected.
+ * @param {(pathValue: string) => string} [options.formatPathArgument] The platform path quoting.
+ * @param {string} [options.platform] The Node platform name.
  * @returns {{status: string, pluginDirectory: string|null, hooksPath: string|null, warning: string|null}} The outcome.
  */
 export function installDeepStackCursor(options) {
@@ -187,15 +225,18 @@ export function installDeepStackCursor(options) {
     const pluginDirectory = join(options.cursorDirectory, plan.pluginDirectoryName);
     mkdirSync(options.cursorDirectory, { recursive: true });
     cpSync(options.pluginSourceDirectory, pluginDirectory, { recursive: true, force: true });
-    const sessionCommand = `${quoteCommandPath(join(pluginDirectory, plan.sessionScriptRelativePath))} ${plan.sessionRuntimeArgument}`;
-    const firstTaskCommand = `python3 ${quoteCommandPath(options.firstTaskHookPath)}`;
-    const hooksPath = join(options.cursorDirectory, 'hooks.json');
-    const current = existsSync(hooksPath)
-        ? JSON.parse(readFileSync(hooksPath, 'utf8'))
-        : { hooks: {} };
-    const merged = mergeDeepStackCursorHooks(current, { sessionCommand, firstTaskCommand });
-    writeFileSync(hooksPath, `${JSON.stringify(merged, null, 2)}\n`);
-    return { status: 'installed', pluginDirectory, hooksPath, warning: null };
+    const formatPathArgument = options.formatPathArgument ?? quoteCommandPath;
+    const pythonCommand = options.pythonCommand ?? DEFAULT_PYTHON_COMMAND;
+    const commands = {
+        sessionCommand: deepStackCursorSessionCommand(pluginDirectory, formatPathArgument, options.platform ?? process.platform),
+        firstTaskCommand: `${pythonCommand} ${formatPathArgument(options.firstTaskHookPath)}`,
+    };
+    updateCursorHooksFile(
+        options.cursorDirectory,
+        configuration => mergeDeepStackCursorHooks(configuration, commands),
+        { createWhenMissing: true },
+    );
+    return { status: 'installed', pluginDirectory, hooksPath: join(options.cursorDirectory, 'hooks.json'), warning: null };
 }
 
 /**
@@ -220,6 +261,8 @@ export function seedCodexDeepStackModels(codexHome) {
  * @param {string} [options.codexHome] The Codex home.
  * @param {string} [options.cursorDirectory] The Cursor home.
  * @param {string} [options.firstTaskHookPath] Absolute path of the hook the first-task command runs.
+ * @param {string} [options.pythonCommand] The interpreter the installer detected.
+ * @param {(pathValue: string) => string} [options.formatPathArgument] The platform path quoting.
  * @param {string} [options.sourceDirectory] A local plugin tree for the Cursor copy.
  * @param {string[]} [options.argumentList] Command-line arguments, for the opt-out flag.
  * @param {Record<string, string|undefined>} [options.environment] The process environment.
@@ -254,6 +297,8 @@ export function installDeepStackForHosts(options = {}, dependencies = {}) {
         cursorDirectory: options.cursorDirectory,
         pluginSourceDirectory: sourceDirectory,
         firstTaskHookPath: options.firstTaskHookPath,
+        pythonCommand: options.pythonCommand,
+        formatPathArgument: options.formatPathArgument,
     });
     if (marketplace.hosts.some(host => host.host === 'codex' && host.status === 'installed') && options.codexHome) {
         seedCodexDeepStackModels(options.codexHome);