@deftai/directive-core 0.86.0 → 0.88.0

package/dist/fs/projection-containment.js

@@ -133,6 +133,46 @@ export function assertWriteTargetSafe(projectDir, targetPath) {
         throw new ProjectionContainmentError(`projection write refused: ${targetAbs} is a symlink on the write path`, { projectDir: resolve(projectDir), targetPath: targetAbs, offendingPath: targetAbs });
     }
 }
+/**
+ * Refuse projection writes that would follow an IN-TREE destination symlink on
+ * the write path (#2912).
+ *
+ * {@link assertProjectionContained} only rejects symlinks that ESCAPE the
+ * project tree, so an in-tree symlink (leaf or parent) pointing at another
+ * checked-in path is silently followed — letting a malicious or mistaken repo
+ * symlink divert a consumer projection write (AGENTS.md, .githooks/**,
+ * .gitattributes, .github/**, .agents/**, vbrief|xbrief/**, package.json, …)
+ * onto an unintended file under operator credentials.
+ *
+ * This guard first runs the escape checks in {@link assertProjectionContained},
+ * then walks every EXISTING component from the project root down to the write
+ * target and refuses the write if ANY of them is a symlink — regardless of
+ * whether the link resolves inside the tree. Call it BEFORE any projection
+ * read/write/mkdir/append on consumer deposit sinks.
+ */
+export function assertDestinationNotSymlink(projectDir, targetPath) {
+    assertProjectionContained(projectDir, targetPath);
+    const projectAbs = resolve(projectDir);
+    const targetAbs = resolve(targetPath);
+    const rel = relative(projectAbs, targetAbs);
+    const segments = rel.split(/[\\/]+/).filter((segment) => segment.length > 0);
+    let current = projectAbs;
+    for (const segment of segments) {
+        current = join(current, segment);
+        let info;
+        try {
+            info = lstatSync(current);
+        }
+        catch {
+            // Component does not exist yet; nothing deeper can exist to follow.
+            break;
+        }
+        if (info.isSymbolicLink()) {
+            throw new ProjectionContainmentError(`projection write refused: ${current} is a symlink on the destination path ` +
+                `(in-tree destination symlinks are refused)`, { projectDir: projectAbs, targetPath: targetAbs, offendingPath: current });
+        }
+    }
+}
 /**
  * Refuse when a lifecycle corpus root is itself a symlink (#2626 category-b).
  */

package/dist/hooks/dispatcher.d.ts

@@ -1,8 +1,9 @@
+import { detectNoDeftDirective } from "../policy/no-deft-directive.js";
 import { type RuntimeAuthorityPolicy } from "../policy/runtime-authority.js";
 import { type VerifyResult } from "../session/verify-session-ritual.js";
 import { type ActiveScopeInspection } from "./scope.js";
 export { hookReadOnlyFromPayload, isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
-export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isSpawnTool, READ_ONLY_HOOK_ENV, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export declare const HOOK_HOSTS: readonly ["claude", "grok", "cursor", "codex"];
 export type HookHost = (typeof HOOK_HOSTS)[number];
 export declare const HOOK_EVENTS: readonly ["session.start", "session.compact", "tool.before"];
@@ -13,7 +14,13 @@ export type CompactHookHost = (typeof COMPACT_HOOK_HOSTS)[number];
 /** Hosts without a native compact hook surface — deposit skips cleanly (#2113). */
 export declare const COMPACT_HOOK_SKIP_HOSTS: readonly ["codex"];
 export type HookVerdict = "allow" | "deny";
-export type HookDecisionCode = "session-start" | "session-start-degraded" | "session-compact-rearm" | "session-compact-rearm-degraded" | "session-compact-noop" | "not-direct-write" | "invalid-input" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready" | "write-ready" | "read-only-deny" | "spawn-explore-ready" | "spawn-ready" | "spawn-not-ready" | "runtime-policy-deny-path" | "runtime-policy-deny-scope";
+export type HookDecisionCode = "session-start" | "session-start-disabled" | "session-start-degraded" | "session-compact-rearm" | "session-compact-rearm-degraded" | "session-compact-noop" | "not-direct-write" | "invalid-input"
+/** Host closed stdin with zero bytes — integration failure, not a policy gate (#2864). */
+ | "stdin-empty" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready" | "write-ready" | "read-only-deny" | "spawn-explore-ready" | "spawn-ready" | "spawn-not-ready" | "runtime-policy-deny-path" | "runtime-policy-deny-scope"
+/** Shell/MCP classifiable push/merge allowed under runtimeAuthority (#2711). */
+ | "shell-op-ready"
+/** Shell/MCP tool seen but command/tool not classifiable as push/merge — fail open (#2711). */
+ | "shell-op-unclassifiable";
 export interface HookDecision {
     readonly verdict: HookVerdict;
     readonly code: HookDecisionCode;
@@ -46,6 +53,8 @@ export interface HookPolicySeams {
         stdout: string;
         stderr: string;
     };
+    /** Test seam for #2926 root opt-out on SessionStart. */
+    readonly detectNoDeftDirective?: typeof detectNoDeftDirective;
     readonly markCompactStale?: (projectRoot: string) => {
         changed: boolean;
         statePath: string;
@@ -62,6 +71,19 @@ export declare function hookToolName(payload: unknown, host?: HookHost): string
 export declare function hookWriteTargetPath(payload: unknown): string | null;
 /** POSIX-ish project-relative path for lifecycle matching. */
 export declare function toProjectRelativePosix(projectRoot: string, targetPath: string): string;
+/**
+ * Lexical "outside project root" predicate used by #2885.
+ * - `".."` / `"../…"` are outside (not bare `startsWith("..")` — that matches `..secret`).
+ * - Absolute relatives and win32 cross-drive paths (`D:/…`) are outside.
+ * - Drive-letter form is win32-only so POSIX children like `D:/tmp/x` stay in-repo.
+ */
+export declare function isLexicalOutsideProjectRoot(relPosix: string): boolean;
+/**
+ * True when a write target is outside `projectRoot` for the active-scope skip (#2885).
+ * Lexically outside paths still fail the skip when a symlink/junction re-enters the project.
+ * When the project root cannot be realpath'd (unit fixtures), lexical classification wins.
+ */
+export declare function isOutsideProjectRootWrite(projectRoot: string, targetPath: string): boolean;
 /**
  * Proposing a scope under xbrief/proposed/ (or legacy vbrief/proposed/) is
  * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
@@ -72,6 +94,11 @@ export declare function normalizeHookProjectRoot(path: string): string;
 export declare function projectRootFromHookPayload(payload: unknown, fallback: string): string;
 export declare function isHookHost(value: string): value is HookHost;
 export declare function isHookEvent(value: string): value is HookEvent;
+/**
+ * Best-effort shell command string from host PreToolUse payloads (#2711).
+ * Hosts disagree on nesting (`tool_input.command` vs top-level `command`).
+ */
+export declare function hookShellCommand(payload: unknown): string | null;
 /** Decide a normalized event using only the P0 direct-write policy. */
 export declare function decideHook(input: HookDispatchInput, seams?: HookPolicySeams): HookDecision;
 /**
@@ -81,6 +108,11 @@ export declare function decideHook(input: HookDispatchInput, seams?: HookPolicyS
  * hook failure and blocks the tool — so Cursor allows must emit explicit
  * `{"permission":"allow"}`. Other hosts keep empty allow so the host permission
  * flow is unchanged.
+ *
+ * Cursor stdout always includes `code` (stable machine-readable decision code)
+ * so agents can distinguish policy denials from host-integration failures
+ * without parsing English (#2864). Exit status still does not encode the
+ * verdict — see hook-dispatch `run()` exit-code contract.
  */
 export declare function renderHostDecision(host: HookHost, decision: HookDecision): string;
 //# sourceMappingURL=dispatcher.d.ts.map

package/dist/hooks/dispatcher.js

@@ -1,14 +1,16 @@
-import { relative, resolve, sep } from "node:path";
+import { realpathSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { hasArtifactSuffix } from "../layout/resolve.js";
-import { evaluateRuntimeAuthorityDirectWrite, loadRuntimeAuthorityFromProject, } from "../policy/runtime-authority.js";
+import { detectNoDeftDirective, NO_DEFT_DIRECTIVE_DISABLED_MESSAGE, NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE, } from "../policy/no-deft-directive.js";
+import { classifyMcpTool, evaluateRuntimeAuthorityDirectWrite, evaluateRuntimeAuthorityShellOp, listShellOps, loadRuntimeAuthorityFromProject, } from "../policy/runtime-authority.js";
 import { markRitualStaleAfterCompact } from "../session/ritual-sentinel.js";
 import { runSessionStartHookWrite } from "../session/session-start-hook.js";
 import { inspectSessionRitual } from "../session/verify-session-ritual.js";
 import { isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
 import { inspectActiveScope } from "./scope.js";
-import { isDirectWriteTool, isSpawnTool } from "./tools.js";
+import { isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool } from "./tools.js";
 export { hookReadOnlyFromPayload, isExploreSpawn, isReadOnlyHookContext } from "./readonly.js";
-export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isSpawnTool, READ_ONLY_HOOK_ENV, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool, isMcpTool, isShellTool, isSpawnTool, MCP_HOOK_MATCHER, MCP_PUSH_MERGE_BARE_NAMES, READ_ONLY_HOOK_ENV, SHELL_HOOK_MATCHER, SHELL_TOOL_NAMES, SPAWN_HOOK_MATCHER, SPAWN_TOOL_NAMES, } from "./tools.js";
 export const HOOK_HOSTS = ["claude", "grok", "cursor", "codex"];
 export const HOOK_EVENTS = ["session.start", "session.compact", "tool.before"];
 /** Hosts that receive compact/resume hook deposits via init/update (#2113). */
@@ -20,7 +22,8 @@ function record(value) {
         ? value
         : null;
 }
-function firstString(...values) {
+/** First non-empty trimmed string from candidates (array form — clear arity for static tools). */
+function firstString(values) {
     for (const value of values) {
         if (typeof value === "string" && value.trim().length > 0)
             return value.trim();
@@ -137,7 +140,14 @@ export function hookWriteTargetPath(payload) {
     if (input === null)
         return null;
     const toolInput = toolInputRecord(input);
-    return firstString(toolInput?.file_path, toolInput?.filePath, toolInput?.path, input.file_path, input.filePath, input.path);
+    return firstString([
+        toolInput?.file_path,
+        toolInput?.filePath,
+        toolInput?.path,
+        input.file_path,
+        input.filePath,
+        input.path,
+    ]);
 }
 /** POSIX-ish project-relative path for lifecycle matching. */
 export function toProjectRelativePosix(projectRoot, targetPath) {
@@ -145,6 +155,57 @@ export function toProjectRelativePosix(projectRoot, targetPath) {
     const rel = relative(resolve(projectRoot), abs);
     return rel.split(sep).join("/").replace(/\\/g, "/");
 }
+function posixRelative(fromAbs, toAbs) {
+    return relative(fromAbs, toAbs).split(sep).join("/").replace(/\\/g, "/");
+}
+/**
+ * Lexical "outside project root" predicate used by #2885.
+ * - `".."` / `"../…"` are outside (not bare `startsWith("..")` — that matches `..secret`).
+ * - Absolute relatives and win32 cross-drive paths (`D:/…`) are outside.
+ * - Drive-letter form is win32-only so POSIX children like `D:/tmp/x` stay in-repo.
+ */
+export function isLexicalOutsideProjectRoot(relPosix) {
+    if (relPosix === ".." || relPosix.startsWith("../") || isAbsolute(relPosix)) {
+        return true;
+    }
+    // path.relative returns absolute drive paths across volumes on Windows only.
+    return process.platform === "win32" && /^[A-Za-z]:\//.test(relPosix);
+}
+/**
+ * True when a write target is outside `projectRoot` for the active-scope skip (#2885).
+ * Lexically outside paths still fail the skip when a symlink/junction re-enters the project.
+ * When the project root cannot be realpath'd (unit fixtures), lexical classification wins.
+ */
+export function isOutsideProjectRootWrite(projectRoot, targetPath) {
+    const projectAbs = resolve(projectRoot);
+    const targetAbs = resolve(projectRoot, targetPath.replace(/\\/g, "/"));
+    const rel = posixRelative(projectAbs, targetAbs);
+    if (!isLexicalOutsideProjectRoot(rel))
+        return false;
+    try {
+        const projectReal = realpathSync(projectAbs);
+        let probe = targetAbs;
+        for (;;) {
+            try {
+                const probeReal = realpathSync(probe);
+                const reenter = posixRelative(projectReal, probeReal);
+                // Empty reenter ⇒ probeReal === projectReal (inside). Lexical-outside reenter ⇒ truly out.
+                if (reenter === "" || !isLexicalOutsideProjectRoot(reenter))
+                    return false;
+                return true;
+            }
+            catch {
+                const parent = dirname(probe);
+                if (parent === probe)
+                    return true;
+                probe = parent;
+            }
+        }
+    }
+    catch {
+        return true;
+    }
+}
 /**
  * Proposing a scope under xbrief/proposed/ (or legacy vbrief/proposed/) is
  * planning, not implementation dispatch — exempt from the active-scope gate (#2625).
@@ -253,6 +314,113 @@ function runtimeAuthorityForDirectWrite(input, toolName, seams, scopePath) {
         return null;
     return deny(input, verdict.code ?? "runtime-policy-deny-path", toolName, verdict.reason ?? "Directive denied this direct write under runtime authority policy.", scopePath);
 }
+/**
+ * Best-effort shell command string from host PreToolUse payloads (#2711).
+ * Hosts disagree on nesting (`tool_input.command` vs top-level `command`).
+ */
+export function hookShellCommand(payload) {
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolInput = toolInputRecord(input);
+    return firstString([
+        toolInput !== null ? toolInput.command : null,
+        toolInput !== null ? toolInput.cmd : null,
+        toolInput !== null ? toolInput.shell_command : null,
+        input.command,
+        input.cmd,
+    ]);
+}
+/** Serialize tool args for MCP classification when nested objects are present (#2711). */
+function hookMcpArgsText(payload) {
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolInput = toolInputRecord(input);
+    if (toolInput === null)
+        return null;
+    try {
+        return JSON.stringify(toolInput);
+    }
+    catch {
+        return null;
+    }
+}
+function loadRuntimeAuthorityPolicySafe(input, seams) {
+    const projectRoot = resolve(input.projectRoot);
+    try {
+        return (seams.loadRuntimeAuthority ?? loadRuntimeAuthorityFromProject)(projectRoot);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Evaluate scopes.push / scopes.merge for Shell/Bash or classifiable MCP tools (#2711).
+ * Returns a full HookDecision (allow or deny). Unclassifiable ops fail open.
+ */
+function decideShellOrMcpRuntimeAuthority(input, toolName, seams) {
+    const projectRoot = resolve(input.projectRoot);
+    const policy = loadRuntimeAuthorityPolicySafe(input, seams);
+    if (policy === null) {
+        return {
+            verdict: "allow",
+            code: "shell-op-unclassifiable",
+            event: input.event,
+            host: input.host,
+            toolName,
+            projectRoot,
+            message: `Directive allowed ${toolName}: runtimeAuthority policy load failed (fail open).`,
+            scopePath: null,
+        };
+    }
+    // Shell: evaluate every classifiable op in compound/multi-line commands (#2711 Greptile).
+    // MCP / bare push-merge names: single tool name maps to at most one op
+    // (includes bare `merge_pull_request` etc. that isMcpTool does not flag).
+    const ops = [];
+    if (isShellTool(toolName)) {
+        const command = hookShellCommand(input.payload);
+        if (command !== null)
+            ops.push(...listShellOps(command));
+    }
+    else {
+        const mcpOp = classifyMcpTool(toolName, hookMcpArgsText(input.payload));
+        if (mcpOp !== null)
+            ops.push(mcpOp);
+    }
+    if (ops.length === 0) {
+        return {
+            verdict: "allow",
+            code: "shell-op-unclassifiable",
+            event: input.event,
+            host: input.host,
+            toolName,
+            projectRoot,
+            message: `${toolName} is classifiable as Shell/MCP but the command/tool was not recognized as ` +
+                "push or merge — fail open (host gap; see runtime-authority.md).",
+            scopePath: null,
+        };
+    }
+    // Deny if any classifiable op is out of scope (compound commands must not short-circuit).
+    for (const op of ops) {
+        const verdict = evaluateRuntimeAuthorityShellOp({ policy, op });
+        if (!verdict.allowed) {
+            return deny(input, verdict.code ?? "runtime-policy-deny-scope", toolName, verdict.reason ??
+                "Directive denied this shell/MCP operation under runtime authority policy.");
+        }
+    }
+    const opsLabel = ops.join("+");
+    return {
+        verdict: "allow",
+        code: "shell-op-ready",
+        event: input.event,
+        host: input.host,
+        toolName,
+        projectRoot,
+        message: `Directive runtimeAuthority allowed classifiable ${opsLabel} via ${toolName}.`,
+        scopePath: null,
+    };
+}
 function inspectMutationGates(input, toolName, seams, options) {
     const projectRoot = resolve(input.projectRoot);
     let ritual;
@@ -298,18 +466,25 @@ function inspectMutationGates(input, toolName, seams, options) {
     if (!scope.ready) {
         const writeTarget = hookWriteTargetPath(input.payload);
         const relTarget = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
-        const proposedPathHint = options.proposedLifecycleExempt &&
-            relTarget !== null &&
-            (relTarget.startsWith("xbrief/proposed/") || relTarget.startsWith("vbrief/proposed/"))
-            ? " For a new proposal under xbrief/proposed/, include a lifecycle artifact " +
-                "filename (*.xbrief.json) in the Write/Edit payload so the gate can exempt " +
-                "planning writes (#2625)."
-            : " Recovery: run `deft scope:activate -- <path>` for the approved xBRIEF, " +
-                (options.proposedLifecycleExempt
-                    ? "or Write a new proposal to xbrief/proposed/*.xbrief.json (planning exemption)."
-                    : "then re-run the pre-start_agent gate stack.");
-        const denyCode = isSpawnTool(toolName) ? "spawn-not-ready" : "scope-not-ready";
-        return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
+        // Active-scope governs in-repo lifecycle work only. Outside-root Write/Edit
+        // (agent memory, $TMPDIR, user config) skips the deny; null/unparseable
+        // targets stay fail-closed. Spawn has no write target → still requires scope (#2885).
+        // Lexical ../ + realpath re-entry guard (not bare startsWith(".."); not symlink aliases).
+        const outsideRoot = writeTarget !== null && isOutsideProjectRootWrite(projectRoot, writeTarget);
+        if (!outsideRoot || isSpawnTool(toolName)) {
+            const proposedPathHint = options.proposedLifecycleExempt &&
+                relTarget !== null &&
+                (relTarget.startsWith("xbrief/proposed/") || relTarget.startsWith("vbrief/proposed/"))
+                ? " For a new proposal under xbrief/proposed/, include a lifecycle artifact " +
+                    "filename (*.xbrief.json) in the Write/Edit payload so the gate can exempt " +
+                    "planning writes (#2625)."
+                : " Recovery: run `deft scope:activate -- <path>` for the approved xBRIEF, " +
+                    (options.proposedLifecycleExempt
+                        ? "or Write a new proposal to xbrief/proposed/*.xbrief.json (planning exemption)."
+                        : "then re-run the pre-start_agent gate stack.");
+            const denyCode = isSpawnTool(toolName) ? "spawn-not-ready" : "scope-not-ready";
+            return deny(input, denyCode, toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
+        }
     }
     const allowCode = isSpawnTool(toolName) ? "spawn-ready" : "write-ready";
     if (!isSpawnTool(toolName)) {
@@ -372,6 +547,24 @@ export function decideHook(input, seams = {}) {
         }
     }
     if (input.event === "session.start") {
+        // #2926: root `.no-deft-directive` wins — skip host SessionStart bookkeeping.
+        const detectOptOut = seams.detectNoDeftDirective ?? detectNoDeftDirective;
+        const optOut = detectOptOut(projectRoot);
+        if (optOut.present) {
+            const message = optOut.inconsistent
+                ? `${NO_DEFT_DIRECTIVE_DISABLED_MESSAGE}. ${NO_DEFT_DIRECTIVE_INCONSISTENT_MESSAGE}`
+                : NO_DEFT_DIRECTIVE_DISABLED_MESSAGE;
+            return {
+                verdict: "allow",
+                code: "session-start-disabled",
+                event: input.event,
+                host: input.host,
+                toolName: null,
+                projectRoot,
+                message,
+                scopePath: null,
+            };
+        }
         try {
             const result = (seams.sessionStart ?? runSessionStartHookWrite)(projectRoot);
             if (result.code !== 0) {
@@ -414,7 +607,12 @@ export function decideHook(input, seams = {}) {
     }
     const toolName = hookToolName(input.payload, input.host);
     if (toolName === null) {
-        return deny(input, "invalid-input", null, missingToolNameMessage({
+        // stdin-empty is a host-integration failure; keep it distinct from invalid-input
+        // so agents can retry without treating it as a policy refusal (#2864).
+        const missingCode = input.payloadContext?.stdinEmpty
+            ? "stdin-empty"
+            : "invalid-input";
+        return deny(input, missingCode, null, missingToolNameMessage({
             host: input.host,
             payload: input.payload,
             context: input.payloadContext,
@@ -446,6 +644,15 @@ export function decideHook(input, seams = {}) {
         }
         return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: false });
     }
+    // Shell/Bash and classifiable MCP: enforce scopes.push / scopes.merge (#2711).
+    // Route bare push/merge MCP names (merge_pull_request, git_push, …) even when
+    // isMcpTool is false — classifyMcpTool is the gate (dispatcher-side, no tools↔policy cycle).
+    // Does not require active-scope ritual — only runtimeAuthority when enabled.
+    if (isShellTool(toolName) ||
+        isMcpTool(toolName) ||
+        classifyMcpTool(toolName, hookMcpArgsText(input.payload)) !== null) {
+        return decideShellOrMcpRuntimeAuthority(input, toolName, seams);
+    }
     if (!isDirectWriteTool(toolName)) {
         return {
             verdict: "allow",
@@ -454,7 +661,7 @@ export function decideHook(input, seams = {}) {
             host: input.host,
             toolName,
             projectRoot,
-            message: `${toolName} is outside the P0 direct-write/spawn enforcement slice.`,
+            message: `${toolName} is outside the P0 direct-write/spawn/shell enforcement slice.`,
             scopePath: null,
         };
     }
@@ -467,11 +674,16 @@ export function decideHook(input, seams = {}) {
  * hook failure and blocks the tool — so Cursor allows must emit explicit
  * `{"permission":"allow"}`. Other hosts keep empty allow so the host permission
  * flow is unchanged.
+ *
+ * Cursor stdout always includes `code` (stable machine-readable decision code)
+ * so agents can distinguish policy denials from host-integration failures
+ * without parsing English (#2864). Exit status still does not encode the
+ * verdict — see hook-dispatch `run()` exit-code contract.
  */
 export function renderHostDecision(host, decision) {
     if (decision.verdict === "allow") {
         if (host === "cursor") {
-            return JSON.stringify({ permission: "allow" });
+            return JSON.stringify({ permission: "allow", code: decision.code });
         }
         return "";
     }
@@ -492,6 +704,7 @@ export function renderHostDecision(host, decision) {
                 permission: "deny",
                 user_message: decision.message,
                 agent_message: decision.message,
+                code: decision.code,
             });
     }
 }

package/dist/hooks/tools.d.ts

@@ -2,10 +2,41 @@
 export declare const DIRECT_WRITE_TOOL_NAMES: readonly ["Edit", "Write", "WriteFile", "CreateFile", "MultiEdit", "NotebookEdit", "StrReplace", "SearchReplace", "Delete", "DeleteFile", "ApplyPatch", "apply_patch"];
 /** PreToolUse spawn / sub-agent dispatch tools (#1185 / #2437). */
 export declare const SPAWN_TOOL_NAMES: readonly ["Task", "SubagentStart", "spawn_subagent", "start_agent", "CreateAgent"];
+/**
+ * Host spellings for Shell/Bash execution tools (#2711).
+ * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ */
+export declare const SHELL_TOOL_NAMES: readonly ["Shell", "Bash", "BashTool", "shell", "bash"];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export declare const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 export declare function isDirectWriteTool(toolName: string): boolean;
 export declare function isSpawnTool(toolName: string): boolean;
+/** True for host Shell/Bash-class tools that carry a command string (#2711). */
+export declare function isShellTool(toolName: string): boolean;
+/**
+ * Best-effort MCP tool detection for runtimeAuthority push/merge scopes (#2711).
+ * Host spellings vary (`mcp__*`, `server__tool`, bare MCP-looking names).
+ * Unclassifiable MCP tools fail open at the operation classifier.
+ *
+ * Bare push/merge names (e.g. `merge_pull_request`) are NOT detected here —
+ * they are classified by `classifyMcpTool` and routed from `decideHook` so
+ * tools.ts stays free of policy imports (#2711 Greptile conf holdout).
+ */
+export declare function isMcpTool(toolName: string): boolean;
+/**
+ * Bare tool names that hosts may emit without mcp__/server__ prefixes and that
+ * `classifyMcpTool` treats as push or merge (#2711).
+ * Keep in sync with classifyMcpTool name patterns (narrow list for PreToolUse matchers).
+ */
+export declare const MCP_PUSH_MERGE_BARE_NAMES: readonly ["merge_pull_request", "merge-pull-request", "pull_request_merge", "pull-request-merge", "merge_pr", "pr_merge", "pr-merge", "git_push", "git-push", "push_branch", "push-branch"];
 export declare const DIRECT_WRITE_HOOK_MATCHER: string;
 export declare const SPAWN_HOOK_MATCHER: string;
+export declare const SHELL_HOOK_MATCHER: string;
+/**
+ * PreToolUse matcher for MCP-class push/merge tools (#2711).
+ * Regex-friendly for Claude/nested hosts. Prefer broad install match +
+ * fail-open classify in the dispatcher over missing a classifiable push/merge
+ * tool name (e.g. `server__push_to_remote` via push+remote).
+ */
+export declare const MCP_HOOK_MATCHER: string;
 //# sourceMappingURL=tools.d.ts.map

package/dist/hooks/tools.js

@@ -21,6 +21,11 @@ export const SPAWN_TOOL_NAMES = [
     "start_agent",
     "CreateAgent",
 ];
+/**
+ * Host spellings for Shell/Bash execution tools (#2711).
+ * Used for runtimeAuthority scopes.push / scopes.merge classification.
+ */
+export const SHELL_TOOL_NAMES = ["Shell", "Bash", "BashTool", "shell", "bash"];
 /** Env override forcing hook-level read-only write denial (#1185). */
 export const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 function normalizedToolName(toolName) {
@@ -28,12 +33,81 @@ function normalizedToolName(toolName) {
 }
 const DIRECT_WRITE_TOOLS = new Set(DIRECT_WRITE_TOOL_NAMES.map(normalizedToolName));
 const SPAWN_TOOLS = new Set(SPAWN_TOOL_NAMES.map(normalizedToolName));
+const SHELL_TOOLS = new Set(SHELL_TOOL_NAMES.map(normalizedToolName));
 export function isDirectWriteTool(toolName) {
     return DIRECT_WRITE_TOOLS.has(normalizedToolName(toolName));
 }
 export function isSpawnTool(toolName) {
     return SPAWN_TOOLS.has(normalizedToolName(toolName));
 }
+/** True for host Shell/Bash-class tools that carry a command string (#2711). */
+export function isShellTool(toolName) {
+    return SHELL_TOOLS.has(normalizedToolName(toolName));
+}
+/**
+ * Best-effort MCP tool detection for runtimeAuthority push/merge scopes (#2711).
+ * Host spellings vary (`mcp__*`, `server__tool`, bare MCP-looking names).
+ * Unclassifiable MCP tools fail open at the operation classifier.
+ *
+ * Bare push/merge names (e.g. `merge_pull_request`) are NOT detected here —
+ * they are classified by `classifyMcpTool` and routed from `decideHook` so
+ * tools.ts stays free of policy imports (#2711 Greptile conf holdout).
+ */
+export function isMcpTool(toolName) {
+    const raw = toolName.trim();
+    if (raw.length === 0)
+        return false;
+    const lower = raw.toLowerCase();
+    if (lower.startsWith("mcp__") || lower.startsWith("mcp_"))
+        return true;
+    if (lower.includes("__") && !isDirectWriteTool(toolName) && !isShellTool(toolName)) {
+        // server__tool style used by some MCP bridges
+        return true;
+    }
+    return false;
+}
+/**
+ * Bare tool names that hosts may emit without mcp__/server__ prefixes and that
+ * `classifyMcpTool` treats as push or merge (#2711).
+ * Keep in sync with classifyMcpTool name patterns (narrow list for PreToolUse matchers).
+ */
+export const MCP_PUSH_MERGE_BARE_NAMES = [
+    "merge_pull_request",
+    "merge-pull-request",
+    "pull_request_merge",
+    "pull-request-merge",
+    "merge_pr",
+    "pr_merge",
+    "pr-merge",
+    "git_push",
+    "git-push",
+    "push_branch",
+    "push-branch",
+];
 export const DIRECT_WRITE_HOOK_MATCHER = DIRECT_WRITE_TOOL_NAMES.join("|");
 export const SPAWN_HOOK_MATCHER = SPAWN_TOOL_NAMES.join("|");
+export const SHELL_HOOK_MATCHER = SHELL_TOOL_NAMES.join("|");
+/**
+ * PreToolUse matcher for MCP-class push/merge tools (#2711).
+ * Regex-friendly for Claude/nested hosts. Prefer broad install match +
+ * fail-open classify in the dispatcher over missing a classifiable push/merge
+ * tool name (e.g. `server__push_to_remote` via push+remote).
+ */
+export const MCP_HOOK_MATCHER = [
+    // Prefixed / server-bridge styles (isMcpTool); dispatcher fail-opens non-ops.
+    "mcp__.*",
+    "mcp_.*",
+    ".*__.*",
+    // Bare names classifyMcpTool recognizes without prefixes.
+    ...MCP_PUSH_MERGE_BARE_NAMES,
+    // Name fragments for hosts that strip server prefixes differently.
+    ".*merge[_-]?pull[_-]?request.*",
+    ".*pull[_-]?request[_-]?merge.*",
+    ".*(?:^|[_-])merge_pr(?:$|[_-]).*",
+    ".*pr[_-]?merge.*",
+    ".*git[_-]?push.*",
+    ".*push[_-]?branch.*",
+    ".*push.*(?:git|branch|remote|ref).*",
+    ".*(?:git|branch|remote|ref).*push.*",
+].join("|");
 //# sourceMappingURL=tools.js.map

package/dist/init-deposit/agent-hooks.d.ts

@@ -1,7 +1,7 @@
 import type { HookHost } from "../hooks/dispatcher.js";
 import { type HostHooksPolicy } from "../policy/host-hooks.js";
 import type { InitDepositIo } from "./constants.js";
-export { DIRECT_WRITE_HOOK_MATCHER, SPAWN_HOOK_MATCHER } from "../hooks/tools.js";
+export { DIRECT_WRITE_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../hooks/tools.js";
 export declare const DEFT_HOOK_COMMAND_MARKER = "deft-hook";
 export declare const LEGACY_DEFT_HOOK_COMMAND_MARKER = "deft hook:dispatch";
 export declare const AGENT_HOOK_PATHS: readonly [".claude/settings.json", ".grok/hooks/deft.json", ".cursor/hooks.json", ".codex/hooks.json"];