@mnemonik/cursor-hooks 0.7.66 → 0.7.71

package/dist/hook.js

@@ -5,18 +5,20 @@ import { exit, stderr, stdin, stdout } from 'node:process';
 import { PRE_BASH_GATE, PRE_EDIT_GATE, PRE_MCP_GATE, PROMPT_CONTEXT, CHECKPOINT_PRESSURE, PRECOMPACT_OBSERVE, SUBAGENT_TRACK, } from './lib/behavior.js';
 import { additionalContext, ask, continueWith, deny, fitCursorContextItems, identifiedContextItems, renderVisibleMnemonikText, } from './lib/cursorOutput.js';
 import { isNonInteractive, parseBypass, resolveConfig } from './lib/env.js';
-import { fetchAmbient, fetchInjections, fetchJit, fetchMcpPrecheck, fetchMcpRecord, reportBypass, reportGateFired, reportSubagent, trackIdeEdit, } from './lib/http.js';
+import { fetchAmbient, fetchInjections, fetchJit, fetchMcpPrecheck, fetchMcpRecord, createPreCompactSnapshot, postContextStats, postProxySuppressionClear, postSessionEnd, reportBypass, reportGateFired, reportSubagent, trackIdeEdit, } from './lib/http.js';
 import { writeProjectFiles } from './lib/files.js';
 import { CURSOR_INLINE_CONTEXT_LIMIT, deliverContext } from './lib/contextOverflow.js';
 import { claimFire } from './lib/dedupGuard.js';
 import { readGitHead } from './lib/git.js';
 import { matchIrreducibleDeny } from './lib/shellTokens.js';
 import { addPathsToGitDirtySnapshot, captureGitDirtyBaseline, diffGitDirtySnapshot, } from '@mnemonik/shared/git-edit-detector';
-import { sessionStateFilePath, sweepStaleSessionDirs } from './lib/sessionState.js';
+import { removeSessionState, sessionStateFilePath, sweepStaleSessionDirs, } from './lib/sessionState.js';
 import { findProjectIdentity } from '@mnemonik/shared/hook-runtime';
 import { cwdOf } from './lib/cwd.js';
 import { isMnemonikToolName } from './lib/mnemonikTool.js';
+import { normalizeMcpArgs, normalizeMcpResult, projectMcpArgsForObservation, } from './lib/mcpPayload.js';
 import { appendProbeLog, buildProbeOutput, probeMode, probeNonce } from './lib/probe.js';
+import { attachPendingResultCue, discardPendingResultCue, extractCursorResultExcerpt, isReadResultTool, rememberPendingResultCue, safeCursorResultText, takePendingResultCue, validCursorToolUseId, } from './lib/resultCue.js';
 import { persistJitDeliveryRef, readPendingJitDeliveryRefs, } from '@mnemonik/shared/jit-delivery-ack';
 import { HOOK_VERSION } from './lib/version.js';
 /**
@@ -55,35 +57,10 @@ function isCursorEditTool(tool) {
  *  `toolArgs.code` (regexed for `mnemonik.code_search(`); an oversized body
  *  must never break the POST. */
 const MAX_TOOL_ARGS_BYTES = 8 * 1024;
-/** Resolve and cap MCP args for the observe-only epoch-writer request. */
-function resolveMcpToolArgs(raw) {
-    let obj;
-    if (raw && typeof raw === 'object')
-        obj = raw;
-    else if (typeof raw === 'string') {
-        try {
-            const parsed = JSON.parse(raw);
-            if (parsed && typeof parsed === 'object')
-                obj = parsed;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    if (!obj)
-        return undefined;
-    let size;
-    try {
-        size = JSON.stringify(obj).length;
-    }
-    catch {
-        return undefined;
-    }
-    if (size <= MAX_TOOL_ARGS_BYTES)
-        return obj;
-    if (typeof obj.code === 'string')
-        return { code: obj.code.slice(0, MAX_TOOL_ARGS_BYTES) };
-    return undefined;
+const MAX_STDIN_BYTES = 1_048_576;
+function objectToolInput(input) {
+    const value = input.tool_input;
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : undefined;
 }
 function captureHostTz() {
     try {
@@ -96,6 +73,7 @@ function captureHostTz() {
 async function readStdin() {
     return new Promise((res) => {
         let buf = '';
+        let bytes = 0;
         let settled = false;
         const finish = (value) => {
             if (settled)
@@ -105,9 +83,12 @@ async function readStdin() {
         };
         stdin.setEncoding('utf8');
         stdin.on('data', (chunk) => {
-            buf += chunk;
-            if (buf.length > 1_048_576)
+            bytes += Buffer.byteLength(chunk, 'utf8');
+            if (bytes > MAX_STDIN_BYTES) {
                 finish(null);
+                return;
+            }
+            buf += chunk;
         });
         stdin.on('end', () => {
             try {
@@ -202,7 +183,7 @@ async function emitGateFired(input, config, tool, mode, outcome) {
     });
 }
 function fileTargetsFromToolInput(toolName, toolInput, cwd) {
-    if (!toolInput)
+    if (!toolInput || typeof toolInput !== 'object' || Array.isArray(toolInput))
         return [];
     const candidates = [];
     const path = toolInput.path ?? toolInput.file_path ?? toolInput.filePath;
@@ -217,6 +198,33 @@ function fileTargetsFromToolInput(toolName, toolInput, cwd) {
     }
     return candidates.map((p) => (p.startsWith('/') ? p : resolve(cwd, p)));
 }
+function pendingResultCueTarget(input) {
+    const tool = input.tool_name ?? '';
+    if (tool === 'Read') {
+        const target = fileTargetsFromToolInput(tool, input.tool_input, cwdOf(input))[0];
+        return target ? `file:${target}` : undefined;
+    }
+    if (tool === 'Shell') {
+        const args = objectToolInput(input);
+        const command = args?.command;
+        if (typeof command === 'string' && isReadResultTool('Shell', args)) {
+            return `command:${command.trim()}`;
+        }
+    }
+    return undefined;
+}
+function dedicatedReadTarget(input) {
+    const path = input.file_path;
+    if (typeof path !== 'string' || !path.trim())
+        return undefined;
+    return `file:${path.startsWith('/') ? path : resolve(cwdOf(input), path)}`;
+}
+function dedicatedShellTarget(input) {
+    const command = input.command;
+    if (typeof command !== 'string' || !isReadResultTool('Shell', { command }))
+        return undefined;
+    return `command:${command.trim()}`;
+}
 async function handleSessionStart(input, config) {
     // Ahead of every early return below: the dirty-set baseline is what makes
     // later shell writes classifiable, and it must be taken even when prompt
@@ -234,21 +242,10 @@ async function handleSessionStart(input, config) {
     });
     if (!isFirstFire)
         writeAllow();
-    // Bus-driven injections only. Legacy /context action prose is deliberately
-    // not merged here, so InjectionBus owns session-start directive timing.
-    //
-    // The server no longer delivers the bootstrap digest on this event: Cursor's
-    // SessionStart `additional_context` field is NOT model-visible (operator
-    // probe 2026-07-02, Cursor 3.9.16; Cursor-acknowledged upstream bug —
-    // composer-handle timing, forum #158452), so a digest emitted here would be
-    // marked "delivered" server-side while the model never saw it. This call now
-    // only WARMS the server's digest cache for the project resolved from the
-    // SessionStart payload's workspace_roots (see cwdOf); the digest itself is
-    // delivered — and the bootstrap obligation satisfied — on the first
-    // `beforeSubmitPrompt` below, which probe-verified as model-visible 9/9. This
-    // handler's own behavior is otherwise unchanged: it fails open (`writeAllow`)
-    // when the server returns no pieces, and still forwards any non-bootstrap
-    // injections the server chooses to send on SessionStart.
+    // Bus-driven injections only. Current Cursor makes SessionStart
+    // additional_context model-visible, so this is the primary bootstrap
+    // carrier. UserPromptSubmit and PostToolUse remain visible late fallbacks
+    // while the server-side obligation is genuinely open.
     const cwd = cwdOf(input);
     const projectId = (await findProjectIdentity(cwd))?.projectId;
     const tz = captureHostTz();
@@ -261,6 +258,17 @@ async function handleSessionStart(input, config) {
         event: 'SessionStart',
         tz,
     });
+    // The compatibility rule is offered on SessionStart and UserPromptSubmit.
+    // Writes are idempotent and fail-open, so an older event sequence can land
+    // the same file at the prompt boundary without churning it.
+    if (injectionsResp?.filesToWrite?.length) {
+        try {
+            await writeProjectFiles(cwd, injectionsResp.filesToWrite);
+        }
+        catch {
+            /* fail-open — a rule-file write must never break the session */
+        }
+    }
     const pieces = [];
     if (injectionsResp?.ok) {
         for (const inj of injectionsResp.injections)
@@ -337,11 +345,8 @@ async function handleBeforeSubmitPrompt(input, config) {
             : Promise.resolve(null),
     ]);
     // Write any server-provided workspace files (the memory-tools rule file)
-    // idempotently. Delivered here on UserPromptSubmit rather than SessionStart:
-    // Cursor kills the FIRST hook fire after a fresh IDE open (the sessionStart
-    // bug), so a SessionStart write never lands on the first session. This fire is
-    // the prompt boundary, which Cursor runs to completion, so the write lands.
-    // Never breaks the session: writeProjectFiles is fail-open and we wrap it too.
+    // idempotently. SessionStart is primary; this remains the compatibility
+    // fallback for older Cursor event sequences. Never breaks the session.
     if (injectionsResp?.filesToWrite?.length) {
         try {
             await writeProjectFiles(cwdOf(input), injectionsResp.filesToWrite);
@@ -446,7 +451,7 @@ async function handlePreToolUse(input, config) {
         cursorSessionId: sessionId(input),
         event: 'PreToolUse',
         toolName: input.tool_name ?? '',
-        toolArgs: input.tool_input,
+        toolArgs: objectToolInput(input),
         filePaths: existingTargets,
     });
     if (!injectionsResp?.ok) {
@@ -495,27 +500,38 @@ async function handlePreToolUse(input, config) {
  * PreToolUse for every OTHER tool — a read, a search, an MCP file tool,
  * whatever Cursor adds next.
  *
- * WHY THIS EXISTS. The accepted reflex-recall design is "all tool actions from
- * day one … Noise controls are budget, per-session dedup, and cue dedup, not a
- * trigger list" (docs/development/memory-adoption.plan.md, "Decisions taken"
- * #1), and Cursor DOES emit `Read` as a preToolUse tool type. Recall must keep
- * firing there. What must NOT follow the read is the grounding gate above: it
- * would report a mutation-shaped outcome for an action that mutates nothing.
+ * WHY THIS EXISTS. Cursor emits Read/Grep/Shell through this generic event.
+ * Those read-result actions record bounded local intent and defer recall to
+ * model-visible PostToolUse; other generic file actions retain pre-tool recall.
+ * None may enter the grounding gate above: it would report a mutation-shaped
+ * outcome for an action that mutates nothing.
  *
  * ADVISORY BY CONSTRUCTION. This branch can add recall to an allow and can
  * never deny — grounding stays with the edit gate, policy with the shell gate.
  * It emits NO `gate_fired` telemetry, exactly like the codex and claude-code
  * generic branches: there is no gate here to report the firing of.
  *
- * CHEAP BY CONSTRUCTION. A payload naming no existing file returns before any
- * network call, so `Task`, `Grep` and friends cost one process that already had
- * to start.
+ * CHEAP BY CONSTRUCTION. Result-cue actions return after a local bounded state
+ * write; another payload naming no existing file returns before any network.
  */
 async function handlePreGenericTool(input, config) {
     if (!config.apiKey)
         writeAllow();
     const cwd = cwdOf(input);
     const tool = input.tool_name ?? '';
+    // Read-result recall belongs to the visible PostToolUse carrier. Remember
+    // only the bounded action intent here; an invisible PreToolUse fetch could
+    // consume server dedup before Cursor has a channel the model can see.
+    const cueTarget = pendingResultCueTarget(input);
+    if (cueTarget && sessionId(input) !== UNKNOWN_SESSION) {
+        rememberPendingResultCue({
+            sessionId: sessionId(input),
+            toolUseId: input.tool_use_id ?? '',
+            target: cueTarget,
+        });
+    }
+    if (tool === 'Read' || tool === 'Grep' || cueTarget)
+        writeAllow();
     const filePaths = fileTargetsFromToolInput(tool, input.tool_input, cwd).filter((path) => existsSync(path));
     if (filePaths.length === 0)
         writeAllow();
@@ -527,7 +543,7 @@ async function handlePreGenericTool(input, config) {
         cursorSessionId: sessionId(input),
         event: 'PreToolUse',
         toolName: tool,
-        toolArgs: input.tool_input,
+        toolArgs: objectToolInput(input),
         filePaths,
     });
     if (!injectionsResp?.ok)
@@ -550,6 +566,23 @@ async function handlePreGenericTool(input, config) {
 async function handlePostToolUse(input, config) {
     const tool = input.tool_name ?? '';
     const cwd = cwdOf(input);
+    const cueTarget = pendingResultCueTarget(input);
+    const toolUseId = validCursorToolUseId(input.tool_use_id);
+    const directExcerpt = extractCursorResultExcerpt({
+        toolName: tool,
+        toolInput: objectToolInput(input),
+        toolOutput: input.tool_output,
+    });
+    const pendingCue = cueTarget && toolUseId && sessionId(input) !== UNKNOWN_SESSION
+        ? takePendingResultCue({
+            sessionId: sessionId(input),
+            toolUseId,
+            target: cueTarget,
+        })
+        : undefined;
+    // Current direct result text wins; BeforeReadFile/AfterShellExecution state
+    // exists only for metadata-only PostToolUse payloads.
+    const resultExcerpt = sessionId(input) === UNKNOWN_SESSION ? undefined : (directExcerpt ?? pendingCue?.excerpt);
     const targets = fileTargetsFromToolInput(tool, input.tool_input, cwd);
     for (const target of targets) {
         await trackIdeEdit({
@@ -577,6 +610,9 @@ async function handlePostToolUse(input, config) {
         cursorSessionId: sessionId(input),
         event: 'PostToolUse',
         toolName: tool,
+        toolArgs: resultExcerpt ? objectToolInput(input) : undefined,
+        toolResultExcerpt: resultExcerpt,
+        toolUseId: resultExcerpt ? toolUseId : undefined,
         // Post-edit grounding (cursor-only server behavior): the server returns
         // the edited file's memory summary as a file_context_required envelope,
         // delivered on postToolUse additional_context — Cursor's only working
@@ -598,10 +634,42 @@ async function handlePostToolUse(input, config) {
     const context = fitInlineContext(pieces);
     writeOutput(additionalContext(await deliverContext(context, sessionId(input))));
 }
+async function handleBeforeReadFile(input, config) {
+    const target = dedicatedReadTarget(input);
+    const excerpt = input.attachments?.length ? undefined : safeCursorResultText(input.content);
+    if (config.apiKey && target && excerpt && sessionId(input) !== UNKNOWN_SESSION) {
+        attachPendingResultCue({ sessionId: sessionId(input), target, excerpt });
+    }
+    writeAllow();
+}
+async function handleAfterShellExecution(input, config) {
+    // Phase-0 order is AfterShellExecution before generic PostToolUse. Observe
+    // writes immediately, then prepare content only; this event has no visible
+    // output field and therefore never marks a cue delivered.
+    await reportShellWrites(input, config);
+    const target = dedicatedShellTarget(input);
+    const excerpt = safeCursorResultText(input.output);
+    if (config.apiKey && target && excerpt && sessionId(input) !== UNKNOWN_SESSION) {
+        attachPendingResultCue({ sessionId: sessionId(input), target, excerpt });
+    }
+    writeAllow();
+}
+async function handlePostToolUseFailure(input, config) {
+    if (input.tool_name === 'Shell')
+        await reportShellWrites(input, config);
+    if (sessionId(input) !== UNKNOWN_SESSION) {
+        discardPendingResultCue({
+            sessionId: sessionId(input),
+            toolUseId: input.tool_use_id,
+            target: pendingResultCueTarget(input),
+        });
+    }
+    writeAllow();
+}
 async function handleBeforeShellExecution(input, config) {
-    // Credits the PREVIOUS shell call's writes: Cursor fires nothing after a
-    // shell command, so the next one is the earliest observation point. Ahead of
-    // the empty-command check, which exits the process.
+    // Compatibility carrier for a previous shell call when AfterShellExecution
+    // did not fire. The rolling snapshot keeps this idempotent with the current
+    // immediate post-shell observer. Ahead of the empty-command early exit.
     await reportShellWrites(input, config);
     const command = (input.command ?? '').toString();
     if (!command.trim())
@@ -613,6 +681,10 @@ async function handleBeforeShellExecution(input, config) {
     // precedes the floor).
     const denyName = matchIrreducibleDeny(command);
     if (denyName) {
+        discardPendingResultCue({
+            sessionId: sessionId(input),
+            target: dedicatedShellTarget(input),
+        });
         await emitGateFired(input, config, 'Shell', 'enforce', `irreducible_deny_${denyName}`);
         writeOutput(deny([
             'MNEMONIK_IRREDUCIBLE_DENY',
@@ -680,6 +752,10 @@ async function handleBeforeShellExecution(input, config) {
         lines.push(fitInjection(checkpointInjection, 4_000));
     }
     if (policyCheck) {
+        discardPendingResultCue({
+            sessionId: sessionId(input),
+            target: dedicatedShellTarget(input),
+        });
         lines.push(fitInjection(policyCheck, 4_000));
     }
     for (const nudge of policyNudges) {
@@ -717,9 +793,11 @@ async function handleBeforeMCPExecution(input, config) {
         await emitGateFired(input, config, tool, 'advisory', 'no_api_key');
         writeAllow();
     }
-    const args = (input.mcp_args ??
-        input.tool_input ??
-        {});
+    const normalizedArgs = normalizeMcpArgs(input);
+    if (!normalizedArgs.ok) {
+        await emitGateFired(input, config, tool, 'advisory', 'invalid_args');
+        writeAllow();
+    }
     // Read .git/HEAD up-front so the `git_head_already_mined` evaluator can
     // compare against `git_mine_history.last_mined_sha`. Soft-fails to undefined
     // when the cwd isn't a git tree or HEAD is unreadable — the server-side
@@ -733,7 +811,7 @@ async function handleBeforeMCPExecution(input, config) {
         projectId: (await findProjectIdentity(cwdOf(input)))?.projectId,
         cursorSessionId: sessionId(input),
         tool,
-        args,
+        args: normalizedArgs.value,
         model: input.model,
         ...(gitHeadSha ? { gitHeadSha } : {}),
     });
@@ -763,20 +841,21 @@ async function handleAfterMCPExecution(input, config) {
     // so the server can populate the retrieved-memory log + embedding cache
     // that backs four precheck evaluators (Cat 2/3/8). Fire-and-forget; any
     // failure leaves the corresponding evaluator fail-open at most.
-    if (config.apiKey && input.mcp_result !== undefined) {
-        const args = (input.mcp_args ??
-            input.tool_input ??
-            {});
-        await fetchMcpRecord({
-            server: config.server,
-            apiKey: config.apiKey,
-            cwd: cwdOf(input),
-            projectId: (await findProjectIdentity(cwdOf(input)))?.projectId,
-            cursorSessionId: sessionId(input),
-            tool,
-            args,
-            result: input.mcp_result,
-        });
+    const normalizedArgs = normalizeMcpArgs(input);
+    const normalizedResult = normalizeMcpResult(input);
+    if (config.apiKey) {
+        if (normalizedArgs.ok && normalizedResult.present) {
+            await fetchMcpRecord({
+                server: config.server,
+                apiKey: config.apiKey,
+                cwd: cwdOf(input),
+                projectId: (await findProjectIdentity(cwdOf(input)))?.projectId,
+                cursorSessionId: sessionId(input),
+                tool,
+                args: normalizedArgs.value,
+                result: normalizedResult.value,
+            });
+        }
         // Cursor cannot render afterMCPExecution output. Keep the epoch and
         // obligation writes, but tell the server to skip injection candidates.
         await fetchInjections({
@@ -787,7 +866,7 @@ async function handleAfterMCPExecution(input, config) {
             cursorSessionId: sessionId(input),
             event: 'PostToolUse',
             toolName: tool,
-            toolArgs: resolveMcpToolArgs(input.mcp_args ?? input.tool_input),
+            toolArgs: projectMcpArgsForObservation(input, MAX_TOOL_ARGS_BYTES),
             observeOnly: true,
         });
     }
@@ -844,12 +923,64 @@ async function handleSubagentLifecycle(input, config, event) {
 async function handlePreCompact(input, config) {
     if (PRECOMPACT_OBSERVE === 'off')
         writeAllow();
+    if (!config.apiKey)
+        writeAllow();
+    const cwd = cwdOf(input);
+    const projectId = (await findProjectIdentity(cwd))?.projectId;
+    const cursorSessionId = sessionId(input);
+    if (cursorSessionId !== UNKNOWN_SESSION &&
+        typeof input.context_tokens === 'number' &&
+        Number.isInteger(input.context_tokens) &&
+        input.context_tokens >= 0) {
+        await postContextStats({
+            server: config.server,
+            apiKey: config.apiKey,
+            cwd,
+            projectId,
+            cursorSessionId,
+            contextTokens: input.context_tokens,
+        });
+    }
+    if (cursorSessionId !== UNKNOWN_SESSION) {
+        await createPreCompactSnapshot({
+            server: config.server,
+            apiKey: config.apiKey,
+            cwd,
+            projectId,
+            cursorSessionId,
+        });
+    }
     const usage = typeof input.context_usage_percent === 'number' ? Math.round(input.context_usage_percent) : -1;
     const msgs = typeof input.messages_to_compact === 'number' ? input.messages_to_compact : -1;
     const first = input.is_first_compaction ? 'first' : 'subsequent';
     await emitGateFired(input, config, 'preCompact', 'advisory', `compact_${first}_u${usage}_m${msgs}`);
     writeAllow();
 }
+async function handleSessionEnd(input, config) {
+    const cursorSessionId = sessionId(input);
+    if (config.apiKey && cursorSessionId !== UNKNOWN_SESSION) {
+        const cwd = cwdOf(input);
+        const projectId = (await findProjectIdentity(cwd))?.projectId;
+        await postProxySuppressionClear({
+            server: config.server,
+            apiKey: config.apiKey,
+            cwd,
+            projectId,
+            cursorSessionId,
+        });
+        await postSessionEnd({
+            server: config.server,
+            apiKey: config.apiKey,
+            cwd,
+            projectId,
+            cursorSessionId,
+            reason: input.reason ?? input.final_status,
+        });
+    }
+    if (cursorSessionId !== UNKNOWN_SESSION)
+        removeSessionState(cursorSessionId);
+    writeAllow();
+}
 async function dispatch(input) {
     if (isNonInteractive())
         writeAllow();
@@ -912,15 +1043,24 @@ async function dispatch(input) {
         case 'postToolUse':
             await handlePostToolUse(input, config);
             break;
+        case 'postToolUseFailure':
+            await handlePostToolUseFailure(input, config);
+            break;
         case 'beforeShellExecution':
             await handleBeforeShellExecution(input, config);
             break;
+        case 'afterShellExecution':
+            await handleAfterShellExecution(input, config);
+            break;
         case 'beforeMCPExecution':
             await handleBeforeMCPExecution(input, config);
             break;
         case 'afterMCPExecution':
             await handleAfterMCPExecution(input, config);
             break;
+        case 'beforeReadFile':
+            await handleBeforeReadFile(input, config);
+            break;
         case 'afterFileEdit':
             await handleAfterFileEdit(input, config);
             break;
@@ -936,6 +1076,9 @@ async function dispatch(input) {
         case 'preCompact':
             await handlePreCompact(input, config);
             break;
+        case 'sessionEnd':
+            await handleSessionEnd(input, config);
+            break;
         default:
             writeAllow();
     }