@deftai/directive-core 0.87.0 → 0.89.0

package/dist/hooks/classify/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Pure write-target / shell-command extraction from host payloads (#2950).
+ * No process I/O — does not resolve against projectRoot or realpath.
+ */
+/**
+ * Best-effort write-target path from host PreToolUse payloads (#2625).
+ * Hosts disagree on nesting (`tool_input.file_path` vs top-level `path`).
+ */
+export declare function hookWriteTargetPath(payload: unknown): string | null;
+/**
+ * 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;
+/** Serialize tool args for MCP classification when nested objects are present (#2711). */
+export declare function hookMcpArgsText(payload: unknown): string | null;
+/**
+ * Collect distinct path-like strings from a payload for fixture assertions.
+ * Write target first when present; does not invent paths from free text.
+ */
+export declare function hookPathSet(payload: unknown): string[];
+//# sourceMappingURL=paths.d.ts.map

package/dist/hooks/classify/paths.js

@@ -0,0 +1,72 @@
+/**
+ * Pure write-target / shell-command extraction from host payloads (#2950).
+ * No process I/O — does not resolve against projectRoot or realpath.
+ */
+import { firstString, record, toolInputRecord } from "./payload.js";
+/**
+ * Best-effort write-target path from host PreToolUse payloads (#2625).
+ * Hosts disagree on nesting (`tool_input.file_path` vs top-level `path`).
+ */
+export function hookWriteTargetPath(payload) {
+    const input = record(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,
+    ]);
+}
+/**
+ * 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). */
+export 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;
+    }
+}
+/**
+ * Collect distinct path-like strings from a payload for fixture assertions.
+ * Write target first when present; does not invent paths from free text.
+ */
+export function hookPathSet(payload) {
+    const seen = new Set();
+    const out = [];
+    const push = (value) => {
+        if (value === null || value.length === 0 || seen.has(value))
+            return;
+        seen.add(value);
+        out.push(value);
+    };
+    push(hookWriteTargetPath(payload));
+    return out;
+}
+//# sourceMappingURL=paths.js.map

package/dist/hooks/classify/payload.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Pure payload field accessors for host PreToolUse shapes (#2950).
+ * No process I/O.
+ */
+export declare function record(value: unknown): Record<string, unknown> | null;
+/** First non-empty trimmed string from candidates. */
+export declare function firstString(values: readonly unknown[]): string | null;
+export declare function fieldPresent(input: Record<string, unknown>, key: string): boolean;
+export declare function fieldString(input: Record<string, unknown>, key: string): string | null;
+/**
+ * Nested tool input record across host spellings
+ * (`tool_input` / `arguments` / `tool_call.arguments` / …).
+ */
+export declare function toolInputRecord(payload: Record<string, unknown>): Record<string, unknown> | null;
+export declare function hookPayloadTopLevelKeys(payload: unknown): string[];
+//# sourceMappingURL=payload.d.ts.map

package/dist/hooks/classify/payload.js

@@ -0,0 +1,45 @@
+/**
+ * Pure payload field accessors for host PreToolUse shapes (#2950).
+ * No process I/O.
+ */
+export function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+/** First non-empty trimmed string from candidates. */
+export function firstString(values) {
+    for (const value of values) {
+        if (typeof value === "string" && value.trim().length > 0)
+            return value.trim();
+    }
+    return null;
+}
+export function fieldPresent(input, key) {
+    return key in input;
+}
+export function fieldString(input, key) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim().length > 0)
+        return value.trim();
+    return null;
+}
+/**
+ * Nested tool input record across host spellings
+ * (`tool_input` / `arguments` / `tool_call.arguments` / …).
+ */
+export function toolInputRecord(payload) {
+    const toolCall = record(payload.tool_call) ?? record(payload.toolCall);
+    return (record(payload.tool_input) ??
+        record(payload.toolInput) ??
+        record(payload.input) ??
+        record(payload.arguments) ??
+        (toolCall !== null ? record(toolCall.arguments) : null));
+}
+export function hookPayloadTopLevelKeys(payload) {
+    const input = record(payload);
+    if (input === null)
+        return [];
+    return Object.keys(input).sort();
+}
+//# sourceMappingURL=payload.js.map

package/dist/hooks/classify/stdin.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pure stdin → payload parse for hook-dispatch (#2734 / #2738 / #2950).
+ * No process I/O — operates on an already-read string.
+ */
+import type { ParsedHookPayload } from "./types.js";
+export declare function stripUtf8Bom(raw: string): string;
+/**
+ * Parse host hook stdin text into a payload + parse context.
+ * Empty → stdinEmpty; invalid JSON without free-form ApplyPatch → parseFailed.
+ */
+export declare function parseHookStdin(raw: string): ParsedHookPayload;
+//# sourceMappingURL=stdin.d.ts.map

package/dist/hooks/classify/stdin.js

@@ -0,0 +1,63 @@
+/**
+ * Pure stdin → payload parse for hook-dispatch (#2734 / #2738 / #2950).
+ * No process I/O — operates on an already-read string.
+ */
+const UTF8_BOM = "\uFEFF";
+const APPLY_PATCH_BEGIN_MARKER = "*** Begin Patch";
+/** Single-file Add/Update only — other *** … File: ops must fail closed (#2738 Greptile). */
+const APPLY_PATCH_MUTATION_LINE_RE = /^\*\*\* (Add File|Update File|Delete File|Move File|Rename File): (.+)$/gm;
+export function stripUtf8Bom(raw) {
+    return raw.startsWith(UTF8_BOM) ? raw.slice(UTF8_BOM.length) : raw;
+}
+function trySynthesizeFreeFormApplyPatch(normalized) {
+    if (!normalized.includes(APPLY_PATCH_BEGIN_MARKER))
+        return null;
+    const mutations = [];
+    for (const match of normalized.matchAll(APPLY_PATCH_MUTATION_LINE_RE)) {
+        const op = match[1];
+        const path = match[2]?.trim();
+        if (op === undefined || !path)
+            continue;
+        mutations.push({ op, path });
+    }
+    if (mutations.length !== 1)
+        return null;
+    const sole = mutations[0];
+    if (sole === undefined || (sole.op !== "Add File" && sole.op !== "Update File"))
+        return null;
+    return {
+        payload: {
+            tool_name: "ApplyPatch",
+            tool_input: {
+                path: sole.path,
+                patch: normalized,
+            },
+        },
+        context: {},
+    };
+}
+/**
+ * Parse host hook stdin text into a payload + parse context.
+ * Empty → stdinEmpty; invalid JSON without free-form ApplyPatch → parseFailed.
+ */
+export function parseHookStdin(raw) {
+    if (raw.trim().length === 0) {
+        return { payload: {}, context: { stdinEmpty: true } };
+    }
+    const normalized = stripUtf8Bom(raw);
+    if (normalized.trim().length === 0) {
+        return { payload: {}, context: { stdinEmpty: true } };
+    }
+    try {
+        return { payload: JSON.parse(normalized), context: {} };
+    }
+    catch {
+        const synthesized = trySynthesizeFreeFormApplyPatch(normalized);
+        if (synthesized !== null)
+            return synthesized;
+        // tool.before is installed only on direct-write matchers, so an unreadable
+        // payload becomes a missing-tool denial rather than a fail-open crash.
+        return { payload: {}, context: { parseFailed: true } };
+    }
+}
+//# sourceMappingURL=stdin.js.map

package/dist/hooks/classify/tool-name.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Pure tool-name resolution from host PreToolUse payloads (#2950 / #2628 / #2669).
+ * No process I/O.
+ */
+import type { ClassifyHookHost, HookPayloadContext } from "./types.js";
+/**
+ * Cursor preToolUse payloads sometimes omit `tool_name` even when the hook matcher
+ * fired for a direct-write tool (#2628). Infer from nested tool input when possible.
+ */
+export declare function inferCursorDirectWriteToolName(payload: Record<string, unknown>): string | null;
+export declare function hookToolName(payload: unknown, host?: ClassifyHookHost | string): string | null;
+export interface MissingToolNameInput {
+    readonly host: ClassifyHookHost | string;
+    readonly payload: unknown;
+    readonly context?: HookPayloadContext;
+}
+export declare function missingToolNameMessage(input: MissingToolNameInput): string;
+//# sourceMappingURL=tool-name.d.ts.map

package/dist/hooks/classify/tool-name.js

@@ -0,0 +1,85 @@
+/**
+ * Pure tool-name resolution from host PreToolUse payloads (#2950 / #2628 / #2669).
+ * No process I/O.
+ */
+import { hookWriteTargetPath } from "./paths.js";
+import { fieldPresent, fieldString, hookPayloadTopLevelKeys, record, toolInputRecord, } from "./payload.js";
+/**
+ * Cursor preToolUse payloads sometimes omit `tool_name` even when the hook matcher
+ * fired for a direct-write tool (#2628). Infer from nested tool input when possible.
+ */
+export function inferCursorDirectWriteToolName(payload) {
+    const toolInput = toolInputRecord(payload);
+    if (toolInput !== null) {
+        if (fieldPresent(toolInput, "new_string") ||
+            fieldPresent(toolInput, "newString") ||
+            fieldPresent(toolInput, "old_string") ||
+            fieldPresent(toolInput, "oldString")) {
+            return "StrReplace";
+        }
+        if (fieldString(toolInput, "contents") !== null ||
+            fieldString(toolInput, "content") !== null ||
+            fieldString(toolInput, "text") !== null) {
+            return "Write";
+        }
+        if (fieldString(toolInput, "patch") !== null ||
+            fieldString(toolInput, "unified_diff") !== null ||
+            fieldString(toolInput, "diff") !== null) {
+            return "ApplyPatch";
+        }
+        if (Array.isArray(toolInput.edits))
+            return "MultiEdit";
+        if (Array.isArray(toolInput.cells) || toolInput.cell_id != null) {
+            return "NotebookEdit";
+        }
+    }
+    // Cursor maps Claude Edit → Write; a write target without contents is still a direct write.
+    if (hookWriteTargetPath(payload) !== null)
+        return "Write";
+    return null;
+}
+export function hookToolName(payload, host) {
+    const input = record(payload);
+    if (input === null)
+        return null;
+    const toolObject = record(input.tool);
+    const toolCall = record(input.tool_call) ?? record(input.toolCall);
+    // OpenAI-style nestings are host-agnostic; checked before Cursor-only inference.
+    const direct = fieldString(input, "tool_name") ??
+        fieldString(input, "toolName") ??
+        fieldString(input, "tool") ??
+        (toolObject !== null ? fieldString(toolObject, "name") : null) ??
+        (toolCall !== null ? fieldString(toolCall, "name") : null);
+    if (direct !== null)
+        return direct;
+    if (host === "cursor")
+        return inferCursorDirectWriteToolName(input);
+    return null;
+}
+export function missingToolNameMessage(input) {
+    const { host, payload, context } = input;
+    if (host === "cursor") {
+        if (context?.stdinEmpty) {
+            return ("Directive denied this Cursor preToolUse event because the host sent an empty payload " +
+                "(stdin was empty — not a session ritual or scope failure). " +
+                "If write tools should pass, update Directive or report the payload shape from Cursor.");
+        }
+        if (context?.parseFailed) {
+            return ("Directive denied this Cursor preToolUse event because the host payload was not valid JSON " +
+                "(host-integration mismatch — not a session ritual or scope failure). " +
+                "If write tools should pass, update Directive or report the payload shape from Cursor.");
+        }
+        const keys = hookPayloadTopLevelKeys(payload);
+        if (keys.length > 0) {
+            return ("Directive denied this Cursor preToolUse event because the host payload omitted a " +
+                "recognizable tool name (host-integration mismatch — not a session ritual or scope failure). " +
+                `Top-level payload keys: ${keys.join(", ")}. ` +
+                "If write tools should pass, update Directive or report the payload shape from Cursor.");
+        }
+        return ("Directive denied this Cursor preToolUse event because the host payload omitted a " +
+            "recognizable tool name (host-integration mismatch — not a session ritual or scope failure). " +
+            "If write tools should pass, update Directive or report the payload shape from Cursor.");
+    }
+    return "Directive denied this matched write event because the host payload omitted its tool name.";
+}
+//# sourceMappingURL=tool-name.js.map

package/dist/hooks/classify/types.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Pure hook classification types (#2950 Phase A).
+ * No process I/O — payload/shape only.
+ */
+/** Host ids that PreToolUse / SessionStart dispatch understands. */
+export declare const CLASSIFY_HOOK_HOSTS: readonly ["claude", "grok", "cursor", "codex"];
+export type ClassifyHookHost = (typeof CLASSIFY_HOOK_HOSTS)[number];
+/**
+ * Write / mutation intent derived from tool identity alone (before policy gates).
+ * Decision codes (allow/deny) live in the dispatcher; this layer only classifies.
+ */
+export type HookWriteIntent = "direct-write" | "spawn" | "shell" | "mcp" | "other" | "unknown";
+/** Stdin parse metadata from hook-dispatch; absent when callers supply payload directly. */
+export interface HookPayloadContext {
+    readonly stdinEmpty?: boolean;
+    readonly parseFailed?: boolean;
+}
+export interface ParsedHookPayload {
+    readonly payload: unknown;
+    readonly context: HookPayloadContext;
+}
+/**
+ * Pure classification of a host PreToolUse (or equivalent) payload.
+ * Paths are extracted as raw host strings — project-relative normalization is
+ * dispatcher-owned (needs projectRoot + optional realpath).
+ */
+export interface HookClassification {
+    readonly toolName: string | null;
+    readonly writeIntent: HookWriteIntent;
+    readonly writeTargetPath: string | null;
+    readonly shellCommand: string | null;
+    readonly topLevelKeys: readonly string[];
+    /** Distinct path-like strings found on the payload (write target first when present). */
+    readonly paths: readonly string[];
+}
+export interface ClassifyHookPayloadInput {
+    readonly payload: unknown;
+    /** Host id; Cursor enables tool-name inference when `tool_name` is omitted. */
+    readonly host?: ClassifyHookHost | string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/hooks/classify/types.js

@@ -0,0 +1,7 @@
+/**
+ * Pure hook classification types (#2950 Phase A).
+ * No process I/O — payload/shape only.
+ */
+/** Host ids that PreToolUse / SessionStart dispatch understands. */
+export const CLASSIFY_HOOK_HOSTS = ["claude", "grok", "cursor", "codex"];
+//# sourceMappingURL=types.js.map

package/dist/hooks/dispatcher.d.ts

@@ -1,8 +1,11 @@
+import { type AuthzState, type HumanOriginGrant } from "../authz/index.js";
+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 HookPayloadContext } from "./classify/index.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,9 +16,17 @@ 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"
+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";
+ | "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"
+/** UAT lease / human-origin grant denial (#2944). */
+ | "authz-uat-deny" | "authz-grant-missing" | "authz-grant-origin-reject" | "authz-grant-scope-deny" | "authz-grant-expired" | "authz-grant-revoked" | "authz-grant-single-use-spent"
+/** Slash-command intent ceiling denial (#1193). */
+ | "intent-ceiling-deny";
 export interface HookDecision {
     readonly verdict: HookVerdict;
     readonly code: HookDecisionCode;
@@ -26,11 +37,6 @@ export interface HookDecision {
     readonly message: string;
     readonly scopePath: string | null;
 }
-/** Stdin parse metadata from hook-dispatch; absent when callers supply payload directly. */
-export interface HookPayloadContext {
-    readonly stdinEmpty?: boolean;
-    readonly parseFailed?: boolean;
-}
 export interface HookDispatchInput {
     readonly host: HookHost;
     readonly event: HookEvent;
@@ -48,20 +54,29 @@ 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;
         message: string;
     };
     readonly loadRuntimeAuthority?: (projectRoot: string) => RuntimeAuthorityPolicy;
+    /**
+     * Test seam for #516 / #2443 story write fence.
+     * Defaults to reading `plan.metadata.swarm.file_scope` (+ writeScope alias)
+     * from the active scope path when present.
+     */
+    readonly loadStoryWriteFence?: (projectRoot: string, scopePath: string | null) => {
+        readonly fileScope: readonly string[];
+        readonly denyPaths: readonly string[];
+    };
+    /** Test seam for #2944 UAT lease + human-origin grants. */
+    readonly loadAuthzState?: (projectRoot: string) => AuthzState;
+    readonly loadAuthzGrants?: (projectRoot: string, state: AuthzState) => readonly HumanOriginGrant[];
+    /** When false, skip writing `.deft/authz/audit.jsonl` (tests). Default true. */
+    readonly authzAudit?: boolean;
 }
-export declare function hookPayloadTopLevelKeys(payload: unknown): string[];
-export declare function hookToolName(payload: unknown, host?: HookHost): string | null;
-/**
- * Best-effort write-target path from host PreToolUse payloads (#2625).
- * Hosts disagree on nesting (`tool_input.file_path` vs top-level `path`).
- */
-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;
 /**