@guilz-dev/belay 0.9.2 → 0.9.4

package/README.md

@@ -44,7 +44,7 @@ equivalent lifecycle points:
 | Gate shell / tools / file mutations | `belay-tool-gate` | `beforeShellExecution`, `preToolUse` | `PreToolUse` | `PreToolUse` |
 | Gate subagent launches | `belay-tool-gate` | `subagentStart` | (via `PreToolUse`) | `SubagentStart` |
 | One-shot approvals | `belay-before-submit` | `beforeSubmitPrompt` | `UserPromptSubmit` | `UserPromptSubmit` |
-| Audit log | `belay-audit` | `postToolUse`, `stop`, `sessionEnd` | `PostToolUse` | `PostToolUse` |
+| Audit log | `belay-audit` | `postToolUse`, `postToolUseFailure`, `stop`, `sessionEnd` | `PostToolUse` | `PostToolUse` |
 
 ## Why
 
@@ -213,7 +213,41 @@ npx @guilz-dev/belay upgrade                # refresh hooks/runtime, migrate con
 **Install scope.** `--scope project` (default) writes artifacts under
 `.cursor/` (or `.claude/`, `.codex/`). `--scope global` installs hooks, runtime,
 and skill under `~/.cursor/`, so the gate is user-wide while `belay.config.json`,
-approvals, and audit stay repo-local.
+approvals, and audit stay repo-local. Cursor scope changes stage the complete target owner before
+publishing `installScope`, then remove only exactly recognized artifacts from the previous owner.
+The config file is replaced atomically so a concurrent hook does not observe a truncate-and-rewrite
+window.
+
+**Cursor source precedence.** Cursor may launch User/global hooks and hooks from multiple open
+Projects for the same event. Belay chooses one effective source from the payload-derived action
+repository: its matching Project install wins when `installScope` is `project`; User/global wins
+when it is `global`. Other sources return a neutral Cursor response without loading the policy core
+or writing audit/control-plane state. In a multi-root workspace, Shell
+`tool_input.working_directory`, then `cwd`, then `workspace_roots` selects the action repository;
+canonical paths prevent symlink aliases from becoming two owners; Project shims persist the
+canonical repository identity at install time. An omitted `installScope` uses its documented
+`project` default. A truly uninitialized repository is neutral to the global source, while a
+present but malformed, unreadable, or invalid config remains selected by the matching Project
+source and reaches Belay's fail-closed config path. A selected but incomplete Project owner fails
+closed for gates and prompts (audit hooks remain safe and diagnostic).
+
+Every managed Cursor hook entry is installed with `failClosed: true`. Cursor can therefore stop an
+actionable prompt, shell, tool, or subagent operation when its runner, shim, or dispatcher cannot
+start, crashes, times out, or returns invalid JSON. Post-action audit events cannot undo an action
+that already completed, and Cursor documents `sessionEnd` as fire-and-forget with its response
+unused; `failClosed` on those entries is defense-in-depth and diagnostics, not rollback. With
+hash-pinned integrity enabled, both Project and global settings, runners, shims, core, and Cursor
+dispatcher are pinned and checked by `belay doctor`. The dispatcher itself contains only payload
+routing and filesystem layout logic; policy and audit modules load only for the selected owner.
+
+Run `belay upgrade --scope global` for a pre-router global Cursor install, then run `belay doctor`.
+A Project upgrade also refreshes an exactly recognized managed global install; doctor reports old
+global generations, origin mismatches, incomplete owners, and managed entries that have not gained
+`failClosed: true`, while a healthy global source shadowed by Project precedence is only a note.
+This mechanism resolves competing sources for the same canonical event; it does not combine
+distinct events such as `beforeShellExecution` and `preToolUse: Shell`, and it does not merge
+repeated deliveries to the effective owner. See
+[ADR-008](./docs/adr/ADR-008-cursor-hook-source-precedence.md).
 
 **Skill-only.** The skill is just a UX layer (slash commands + guidance) and does
 **not** enable gating on its own. Install from [skills.sh](https://skills.sh/guilz-dev/belay)

package/dist/adapters/codex/hooks.d.ts

@@ -1,5 +1,6 @@
 export declare const CODEX_HOOKS_BEGIN = "# --- BELAY MANAGED HOOKS BEGIN (managed by belay; do not edit) ---";
 export declare const CODEX_HOOKS_END = "# --- BELAY MANAGED HOOKS END ---";
+export declare function codexHooksTomlIncludesCommand(content: string, command: string): boolean;
 /**
  * Render belay's Codex lifecycle hooks as a marker-delimited TOML block for `.codex/config.toml`.
  * The block is replaced wholesale on re-init/upgrade (see mergeCodexHooksToml), so we avoid a

package/dist/adapters/codex/hooks.js

@@ -12,6 +12,9 @@ const CODEX_HOOK_SPECS = [
 function tomlString(value) {
     return `"${value.replaceAll('\\', '\\\\').replaceAll('"', '\\"')}"`;
 }
+export function codexHooksTomlIncludesCommand(content, command) {
+    return content.includes(`command = ${tomlString(command)}`);
+}
 function runnerCommand(platform, hooksDir, repoRoot, hookName, ...args) {
     return buildRunnerInvocation(platform, hooksDir, repoRoot, hookName, ...args);
 }

package/dist/adapters/codex/runtime-entry.d.ts

@@ -1,3 +1,6 @@
+export declare function resolveCodexActionCwd(payload: Record<string, unknown>, fallbackCwd?: string, options?: {
+    includeToolInputCwd?: boolean;
+}): string;
 export declare function runBeforeSubmitPromptHook(): Promise<void>;
 export declare function runToolGateHook(eventName: string): Promise<void>;
 export declare function runShellGateHook(): Promise<void>;

package/dist/adapters/codex/runtime-entry.js

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import process from 'node:process';
 import { codexLayout } from '../layouts/codex.js';
 import { appendObservedAudit, createDefaultGateRuntimeDeps, evaluateGatedAction, gateUnmappedToolVerdict, gateVerdictToCodexPreToolUseResponse, gateVerdictToCodexUserPromptResponse, processApprovalPrompt, resolveGateConfig, } from '../shared/gate-runtime.js';
@@ -21,6 +22,22 @@ async function readStdinJson() {
 function jsonResponse(value) {
     process.stdout.write(`${JSON.stringify(value)}\n`);
 }
+function nonEmptyPathString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+export function resolveCodexActionCwd(payload, fallbackCwd = process.cwd(), options = {}) {
+    const toolInput = payload.tool_input !== null && typeof payload.tool_input === 'object'
+        ? payload.tool_input
+        : undefined;
+    const nestedCwd = options.includeToolInputCwd
+        ? (nonEmptyPathString(toolInput?.working_directory) ?? nonEmptyPathString(toolInput?.cwd))
+        : undefined;
+    const payloadCwd = nonEmptyPathString(payload.cwd);
+    const workspaceRoot = Array.isArray(payload.workspace_roots)
+        ? payload.workspace_roots.map(nonEmptyPathString).find(Boolean)
+        : undefined;
+    return path.resolve(nestedCwd ?? payloadCwd ?? workspaceRoot ?? fallbackCwd);
+}
 async function loadRuntimeContext(cwd) {
     const repoRoot = findRepoRoot(cwd, codexLayout);
     const configPath = codexLayout.configPath(repoRoot);
@@ -137,7 +154,8 @@ export async function runBeforeSubmitPromptHook() {
     try {
         const payload = await readStdinJson();
         const prompt = String(payload.prompt ?? payload.user_message ?? '');
-        const ctx = await loadRuntimeContext(process.cwd());
+        const cwd = resolveCodexActionCwd(payload);
+        const ctx = await loadRuntimeContext(cwd);
         const deps = createDefaultGateRuntimeDeps();
         const result = await processApprovalPrompt(ctx, deps, prompt);
         jsonResponse(gateVerdictToCodexUserPromptResponse(result));
@@ -155,9 +173,10 @@ export async function runBeforeSubmitPromptHook() {
 export async function runToolGateHook(eventName) {
     try {
         const payload = await readStdinJson();
-        const cwd = process.cwd();
         const toolName = String(payload.tool_name ?? payload.toolName ?? '');
         const kind = resolveCodexGateKind(eventName, toolName);
+        const includeToolInputCwd = (eventName === 'PreToolUse' || eventName === 'preToolUse') && kind === 'shell';
+        const cwd = resolveCodexActionCwd(payload, process.cwd(), { includeToolInputCwd });
         const ctx = await loadRuntimeContext(cwd);
         const deps = createDefaultGateRuntimeDeps();
         if (!kind) {
@@ -201,7 +220,7 @@ export async function runShellGateHook() {
     try {
         const payload = await readStdinJson();
         const command = extractString(payload.tool_input, 'command') || String(payload.command ?? '');
-        const cwd = process.cwd();
+        const cwd = resolveCodexActionCwd(payload, process.cwd(), { includeToolInputCwd: true });
         const ctx = await loadRuntimeContext(cwd);
         const deps = createDefaultGateRuntimeDeps();
         const verdict = await evaluateGatedAction(ctx, deps, {
@@ -227,7 +246,11 @@ export async function runShellGateHook() {
 export async function runAuditHook(eventName) {
     try {
         const payload = await readStdinJson();
-        const ctx = await loadRuntimeContext(process.cwd());
+        const toolName = String(payload.tool_name ?? payload.toolName ?? '');
+        const kind = resolveCodexGateKind(eventName, toolName);
+        const includeToolInputCwd = (eventName === 'PreToolUse' || eventName === 'preToolUse') && kind === 'shell';
+        const cwd = resolveCodexActionCwd(payload, process.cwd(), { includeToolInputCwd });
+        const ctx = await loadRuntimeContext(cwd);
         const deps = createDefaultGateRuntimeDeps();
         await appendObservedAudit(ctx, deps, eventName, payload);
         jsonResponse({});

package/dist/adapters/cursor/cwd-resolution.d.ts

@@ -0,0 +1,10 @@
+export type CursorActionCwdSource = 'tool_input.working_directory' | 'cwd' | 'workspace_roots' | 'fallback';
+export interface CursorActionCwdResolution {
+    cwd: string;
+    source: CursorActionCwdSource;
+    fromPayload: boolean;
+}
+export declare function resolveCursorActionCwdDetails(payload: Record<string, unknown>, fallback?: string): CursorActionCwdResolution;
+export declare function isGlobalCursorHookRuntime(): boolean;
+export declare function isUnsafeGlobalHookFallback(resolution: CursorActionCwdResolution, globalRuntime?: boolean): boolean;
+export declare const GLOBAL_HOOK_WORKSPACE_MISSING_MESSAGE: string;

package/dist/adapters/cursor/cwd-resolution.js

@@ -0,0 +1,58 @@
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+function nonEmptyPathString(value) {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+export function resolveCursorActionCwdDetails(payload, fallback = process.cwd()) {
+    const toolInput = payload.tool_input;
+    const toolInputWorkingDirectory = toolInput !== null && typeof toolInput === 'object' && !Array.isArray(toolInput)
+        ? nonEmptyPathString(toolInput.working_directory)
+        : undefined;
+    const topLevelCwd = nonEmptyPathString(payload.cwd);
+    const workspaceRoot = Array.isArray(payload.workspace_roots)
+        ? payload.workspace_roots.map(nonEmptyPathString).find(Boolean)
+        : undefined;
+    if (toolInputWorkingDirectory) {
+        return {
+            cwd: path.resolve(toolInputWorkingDirectory),
+            source: 'tool_input.working_directory',
+            fromPayload: true,
+        };
+    }
+    if (topLevelCwd) {
+        return {
+            cwd: path.resolve(topLevelCwd),
+            source: 'cwd',
+            fromPayload: true,
+        };
+    }
+    if (workspaceRoot) {
+        return {
+            cwd: path.resolve(workspaceRoot),
+            source: 'workspace_roots',
+            fromPayload: true,
+        };
+    }
+    return {
+        cwd: path.resolve(fallback),
+        source: 'fallback',
+        fromPayload: false,
+    };
+}
+export function isGlobalCursorHookRuntime() {
+    try {
+        const runtimePath = path.resolve(fileURLToPath(import.meta.url));
+        const globalRuntimeDir = path.resolve(path.join(os.homedir(), '.cursor', 'belay', 'runtime'));
+        return (runtimePath === globalRuntimeDir || runtimePath.startsWith(`${globalRuntimeDir}${path.sep}`));
+    }
+    catch {
+        return false;
+    }
+}
+export function isUnsafeGlobalHookFallback(resolution, globalRuntime = isGlobalCursorHookRuntime()) {
+    return !resolution.fromPayload && globalRuntime;
+}
+export const GLOBAL_HOOK_WORKSPACE_MISSING_MESSAGE = 'belay could not determine the workspace for this action from the Cursor hook payload. ' +
+    'Open the target project workspace and retry, or run belay doctor. ' +
+    'To stop global hooks: belay uninstall --scope global';

package/dist/adapters/cursor/dispatcher-generation.d.ts

@@ -0,0 +1,3 @@
+export declare const CURSOR_DISPATCHER_GENERATION = "cursor-owner-router-v1";
+export declare const CURSOR_DISPATCHER_GENERATION_HEADER: string;
+export declare function hasCurrentCursorDispatcherGeneration(source: string): boolean;

package/dist/adapters/cursor/dispatcher-generation.js

@@ -0,0 +1,5 @@
+export const CURSOR_DISPATCHER_GENERATION = 'cursor-owner-router-v1';
+export const CURSOR_DISPATCHER_GENERATION_HEADER = `export const BELAY_CURSOR_DISPATCHER_GENERATION = ${JSON.stringify(CURSOR_DISPATCHER_GENERATION)};\n`;
+export function hasCurrentCursorDispatcherGeneration(source) {
+    return source.startsWith(CURSOR_DISPATCHER_GENERATION_HEADER);
+}

package/dist/adapters/cursor/hook-dispatch-entry.d.ts

@@ -0,0 +1,7 @@
+import { type CursorHookKind, type CursorHookOrigin } from './hook-router.js';
+export interface DispatchCursorHookParams {
+    origin: CursorHookOrigin;
+    kind: CursorHookKind;
+    eventName: string;
+}
+export declare function dispatchCursorHook(params: DispatchCursorHookParams): Promise<void>;

package/dist/adapters/cursor/hook-dispatch-entry.js

@@ -0,0 +1,126 @@
+import process from 'node:process';
+import { routeCursorHook } from './hook-router.js';
+async function readStdinPayload() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(typeof chunk === 'string' ? chunk : chunk.toString('utf8'));
+    }
+    const raw = chunks.join('').trim();
+    if (!raw) {
+        return { ok: false };
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        return parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)
+            ? { ok: true, payload: parsed }
+            : { ok: false };
+    }
+    catch {
+        return { ok: false };
+    }
+}
+function neutralResponse(kind) {
+    if (kind === 'before-submit') {
+        return { continue: true };
+    }
+    if (kind === 'audit') {
+        return {};
+    }
+    return { permission: 'allow' };
+}
+function failClosedResponse(kind, message) {
+    if (kind === 'audit') {
+        console.error(`belay audit hook skipped: ${message}`);
+        return {};
+    }
+    if (kind === 'before-submit') {
+        return { continue: false, user_message: message };
+    }
+    return { permission: 'deny', user_message: message };
+}
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isRecognizedPayload(params, payload) {
+    if (params.kind === 'before-submit') {
+        return params.eventName === 'beforeSubmitPrompt' && typeof payload.prompt === 'string';
+    }
+    if (params.kind === 'shell-gate') {
+        return params.eventName === 'beforeShellExecution' && typeof payload.command === 'string';
+    }
+    if (params.kind === 'tool-gate') {
+        if (params.eventName === 'preToolUse' || params.eventName === 'PreToolUse') {
+            return isNonEmptyString(payload.tool_name) && isRecord(payload.tool_input);
+        }
+        return (params.eventName === 'subagentStart' &&
+            isNonEmptyString(payload.subagent_type) &&
+            typeof payload.task === 'string');
+    }
+    if (params.eventName === 'postToolUse') {
+        return (isNonEmptyString(payload.tool_name) &&
+            isRecord(payload.tool_input) &&
+            typeof payload.tool_output === 'string');
+    }
+    if (params.eventName === 'postToolUseFailure') {
+        return (isNonEmptyString(payload.tool_name) &&
+            isRecord(payload.tool_input) &&
+            typeof payload.error_message === 'string' &&
+            typeof payload.failure_type === 'string');
+    }
+    if (params.eventName === 'stop') {
+        return typeof payload.status === 'string' && typeof payload.loop_count === 'number';
+    }
+    if (params.eventName === 'sessionEnd') {
+        return isNonEmptyString(payload.session_id) && typeof payload.reason === 'string';
+    }
+    return false;
+}
+async function executeCoreHandler(params, payload) {
+    const coreModulePath = './core.mjs';
+    const core = (await import(coreModulePath));
+    if (params.kind === 'before-submit') {
+        return core.handleBeforeSubmitPromptHook(payload);
+    }
+    if (params.kind === 'shell-gate') {
+        return core.handleShellGateHook(payload);
+    }
+    if (params.kind === 'tool-gate') {
+        return core.handleToolGateHook(params.eventName, payload);
+    }
+    return core.handleAuditHook(params.eventName, payload);
+}
+async function dispatchCursorHookResponse(params) {
+    const input = await readStdinPayload();
+    if (!input.ok) {
+        return failClosedResponse(params.kind, 'belay received malformed Cursor hook input.');
+    }
+    if (!isRecognizedPayload(params, input.payload)) {
+        return neutralResponse(params.kind);
+    }
+    try {
+        const route = routeCursorHook({
+            origin: params.origin,
+            kind: params.kind,
+            eventName: params.eventName,
+            payload: input.payload,
+        });
+        if (route.decision === 'neutral') {
+            return neutralResponse(params.kind);
+        }
+        if (route.decision === 'fail_closed') {
+            return failClosedResponse(params.kind, route.message);
+        }
+        return await executeCoreHandler(params, input.payload);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return failClosedResponse(params.kind, `belay failed while dispatching this Cursor hook: ${detail}`);
+    }
+}
+export async function dispatchCursorHook(params) {
+    const response = await dispatchCursorHookResponse(params);
+    process.stdout.write(`${JSON.stringify(response)}\n`);
+}

package/dist/adapters/cursor/hook-router.d.ts

@@ -0,0 +1,23 @@
+export type CursorHookOrigin = {
+    scope: 'project';
+    repoRoot: string;
+} | {
+    scope: 'global';
+};
+export type CursorHookKind = 'before-submit' | 'shell-gate' | 'tool-gate' | 'audit';
+export type CursorHookRoute = {
+    decision: 'execute';
+    repoRoot: string;
+} | {
+    decision: 'neutral';
+} | {
+    decision: 'fail_closed';
+    message: string;
+};
+export interface RouteCursorHookParams {
+    origin: CursorHookOrigin;
+    kind: CursorHookKind;
+    eventName?: string;
+    payload: Record<string, unknown>;
+}
+export declare function routeCursorHook(params: RouteCursorHookParams): CursorHookRoute;

package/dist/adapters/cursor/hook-router.js

@@ -0,0 +1,266 @@
+import { accessSync, constants, existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { resolveCursorActionCwdDetails } from './cwd-resolution.js';
+import { cursorRoutingConfigPath, cursorRoutingHooksDir, cursorRoutingHooksSettingsPath, cursorRoutingRuntimeDir, findCursorRoutingRepoRoot, } from './routing-layout.js';
+function canonicalExistingPath(value) {
+    if (!existsSync(value)) {
+        return undefined;
+    }
+    try {
+        return realpathSync(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function hookScriptFor(kind) {
+    if (kind === 'before-submit') {
+        return 'belay-before-submit.mjs';
+    }
+    if (kind === 'shell-gate') {
+        return 'belay-shell-gate.mjs';
+    }
+    if (kind === 'tool-gate') {
+        return 'belay-tool-gate.mjs';
+    }
+    return 'belay-audit.mjs';
+}
+function hookCommandFor(kind) {
+    return hookScriptFor(kind).replace(/\.mjs$/, '');
+}
+function eventNameFor(params) {
+    if (params.eventName) {
+        return params.eventName;
+    }
+    if (params.kind === 'before-submit') {
+        return 'beforeSubmitPrompt';
+    }
+    if (params.kind === 'shell-gate') {
+        return 'beforeShellExecution';
+    }
+    if (params.kind === 'tool-gate') {
+        return typeof params.payload.subagent_type === 'string' ? 'subagentStart' : 'preToolUse';
+    }
+    if (typeof params.payload.error_message === 'string') {
+        return 'postToolUseFailure';
+    }
+    if (typeof params.payload.status === 'string') {
+        return 'stop';
+    }
+    if (typeof params.payload.session_id === 'string') {
+        return 'sessionEnd';
+    }
+    return 'postToolUse';
+}
+function selectedRunnerPath(hooksDir) {
+    const runnerPath = path.join(hooksDir, process.platform === 'win32' ? 'belay-runner.ps1' : 'belay-runner');
+    const canonicalPath = canonicalExistingPath(runnerPath);
+    if (!canonicalPath) {
+        return undefined;
+    }
+    try {
+        if (!statSync(canonicalPath).isFile()) {
+            return undefined;
+        }
+        accessSync(canonicalPath, process.platform === 'win32' ? constants.R_OK : constants.X_OK);
+        return canonicalPath;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRegularFile(filePath) {
+    const canonicalPath = canonicalExistingPath(filePath);
+    if (!canonicalPath) {
+        return false;
+    }
+    try {
+        return statSync(canonicalPath).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+function expectedHookArgs(kind, eventName) {
+    return kind === 'tool-gate' || kind === 'audit' ? [eventName] : [];
+}
+function commandInvokesProjectHook(command, runnerPath, kind, eventName) {
+    const hookCommand = hookCommandFor(kind);
+    const args = expectedHookArgs(kind, eventName);
+    if (process.platform !== 'win32') {
+        const expected = [`'${runnerPath.replaceAll("'", "'\\''")}'`, hookCommand, ...args].join(' ');
+        return command === expected;
+    }
+    const encoded = command.match(/^"[^"\r\n]+" -NoLogo -NoProfile -NonInteractive -ExecutionPolicy Bypass -EncodedCommand ([A-Za-z0-9+/=]+)$/)?.[1];
+    if (!encoded) {
+        return false;
+    }
+    const quotePowerShellLiteral = (value) => `'${value.replaceAll("'", "''")}'`;
+    const expected = [
+        '&',
+        quotePowerShellLiteral(runnerPath),
+        ...[hookCommand, ...args].map(quotePowerShellLiteral),
+    ].join(' ');
+    return Buffer.from(encoded, 'base64').toString('utf16le') === expected;
+}
+function expectedMatcher(eventName, payload) {
+    if (eventName === 'preToolUse') {
+        return typeof payload.tool_name === 'string' ? payload.tool_name : undefined;
+    }
+    if (eventName === 'subagentStart') {
+        return typeof payload.subagent_type === 'string' ? payload.subagent_type : undefined;
+    }
+    return undefined;
+}
+function hasManagedProjectHookEntry(repoRoot, runnerPath, params) {
+    const eventName = eventNameFor(params);
+    const matcher = expectedMatcher(eventName, params.payload);
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(cursorRoutingHooksSettingsPath(repoRoot), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        return false;
+    }
+    const hooks = parsed.hooks;
+    if (hooks === null || typeof hooks !== 'object' || Array.isArray(hooks)) {
+        return false;
+    }
+    const entries = hooks[eventName];
+    if (!Array.isArray(entries)) {
+        return false;
+    }
+    return entries.some((entry) => {
+        if (entry === null || typeof entry !== 'object' || Array.isArray(entry)) {
+            return false;
+        }
+        const definition = entry;
+        return (definition.failClosed === true &&
+            definition.matcher === matcher &&
+            typeof definition.command === 'string' &&
+            commandInvokesProjectHook(definition.command, runnerPath, params.kind, eventName));
+    });
+}
+function hasMatchingProjectShim(repoRoot, kind) {
+    let source;
+    try {
+        source = readFileSync(path.join(cursorRoutingHooksDir(repoRoot), hookScriptFor(kind)), 'utf8');
+    }
+    catch {
+        return false;
+    }
+    return (source.includes("from '../belay/runtime/dispatcher.mjs'") &&
+        source.includes(`origin: ${JSON.stringify({ scope: 'project', repoRoot })}`));
+}
+function hasCallableProjectOwner(repoRoot, params) {
+    const hooksDir = cursorRoutingHooksDir(repoRoot);
+    const runnerPath = selectedRunnerPath(hooksDir);
+    return Boolean(runnerPath &&
+        isRegularFile(path.join(cursorRoutingRuntimeDir(repoRoot), 'dispatcher.mjs')) &&
+        hasMatchingProjectShim(repoRoot, params.kind) &&
+        hasManagedProjectHookEntry(repoRoot, runnerPath, params));
+}
+function payloadForKind(payload, kind) {
+    if (kind === 'before-submit' || kind === 'shell-gate') {
+        return payload;
+    }
+    if (kind === 'tool-gate' && payload.tool_name === 'Shell') {
+        return payload;
+    }
+    const toolInput = payload.tool_input;
+    if (toolInput === null || typeof toolInput !== 'object' || Array.isArray(toolInput)) {
+        return payload;
+    }
+    const { working_directory: _workingDirectory, ...withoutWorkingDirectory } = toolInput;
+    return { ...payload, tool_input: withoutWorkingDirectory };
+}
+function selectedActionPath(payload) {
+    const toolInput = payload.tool_input;
+    if (toolInput !== null && typeof toolInput === 'object' && !Array.isArray(toolInput)) {
+        const workingDirectory = toolInput.working_directory;
+        if (typeof workingDirectory === 'string' && workingDirectory.trim()) {
+            return workingDirectory.trim();
+        }
+    }
+    if (typeof payload.cwd === 'string' && payload.cwd.trim()) {
+        return payload.cwd.trim();
+    }
+    if (!Array.isArray(payload.workspace_roots)) {
+        return undefined;
+    }
+    for (const root of payload.workspace_roots) {
+        if (typeof root === 'string' && root.trim()) {
+            return root.trim();
+        }
+    }
+    return undefined;
+}
+function readInstallScope(repoRoot) {
+    const configPath = cursorRoutingConfigPath(repoRoot);
+    let source;
+    try {
+        source = readFileSync(configPath, 'utf8');
+    }
+    catch (error) {
+        return error.code === 'ENOENT' ? 'missing' : 'project';
+    }
+    try {
+        const parsed = JSON.parse(source);
+        if (parsed !== null &&
+            typeof parsed === 'object' &&
+            !Array.isArray(parsed) &&
+            parsed.installScope === 'global') {
+            return 'global';
+        }
+    }
+    catch {
+        // A present config that cannot be read or parsed must retain Project ownership so the
+        // selected Project hook reaches its fail-closed core path. Only a missing config is neutral.
+    }
+    return 'project';
+}
+export function routeCursorHook(params) {
+    const relevantPayload = payloadForKind(params.payload, params.kind);
+    const selectedPath = selectedActionPath(relevantPayload);
+    if (!selectedPath || !path.isAbsolute(selectedPath)) {
+        return { decision: 'fail_closed', message: 'belay could not determine the workspace.' };
+    }
+    const resolution = resolveCursorActionCwdDetails(relevantPayload, '/');
+    const canonicalCwd = resolution.fromPayload ? canonicalExistingPath(resolution.cwd) : undefined;
+    if (!canonicalCwd) {
+        return { decision: 'fail_closed', message: 'belay could not determine the workspace.' };
+    }
+    const repoRoot = canonicalExistingPath(findCursorRoutingRepoRoot(canonicalCwd));
+    if (!repoRoot) {
+        return { decision: 'neutral' };
+    }
+    const installScope = readInstallScope(repoRoot);
+    if (installScope === 'missing') {
+        return { decision: 'neutral' };
+    }
+    if (installScope === 'global') {
+        return params.origin.scope === 'global'
+            ? { decision: 'execute', repoRoot }
+            : { decision: 'neutral' };
+    }
+    if (params.origin.scope === 'project' &&
+        canonicalExistingPath(params.origin.repoRoot) !== repoRoot) {
+        return { decision: 'neutral' };
+    }
+    const callableProjectOwner = hasCallableProjectOwner(repoRoot, params);
+    if (params.origin.scope === 'global') {
+        return callableProjectOwner
+            ? { decision: 'neutral' }
+            : {
+                decision: 'fail_closed',
+                message: 'belay project hook owner is unavailable; the global sentinel blocked this action.',
+            };
+    }
+    const complete = callableProjectOwner && isRegularFile(path.join(cursorRoutingRuntimeDir(repoRoot), 'core.mjs'));
+    return complete
+        ? { decision: 'execute', repoRoot }
+        : { decision: 'fail_closed', message: 'belay project hook installation is incomplete.' };
+}

package/dist/adapters/cursor/hooks.d.ts

@@ -3,5 +3,10 @@ import type { HookEntry, HooksFile } from '../../types.js';
 export declare function managedShellPreToolUseEntry(platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HookEntry;
 /** @deprecated Use {@link managedShellPreToolUseEntry}. */
 export declare const legacyManagedShellPreToolUseEntry: typeof managedShellPreToolUseEntry;
+export declare function stripCursorHooksFile(current: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HooksFile;
 export declare function mergeCursorHooksFile(current: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HooksFile;
+export declare function legacyManagedShellPreToolUseVariants(platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HookEntry[];
+export declare function hasLegacyCursorDoubleShellGates(hooks: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): boolean;
+/** @deprecated Use {@link hasLegacyCursorDoubleShellGates}. */
 export declare function hasDuplicateCursorShellGates(hooks: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): boolean;
+export declare function hasManagedCursorHookEntries(hooks: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): boolean;