@deftai/directive-core 0.79.4 → 0.80.0

package/dist/hooks/dispatcher.d.ts

@@ -1,12 +1,19 @@
+import { type RuntimeAuthorityPolicy } from "../policy/runtime-authority.js";
 import { type VerifyResult } from "../session/verify-session-ritual.js";
 import { type ActiveScopeInspection } from "./scope.js";
-export { DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool } 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 declare const HOOK_HOSTS: readonly ["claude", "grok", "cursor", "codex"];
 export type HookHost = (typeof HOOK_HOSTS)[number];
-export declare const HOOK_EVENTS: readonly ["session.start", "tool.before"];
+export declare const HOOK_EVENTS: readonly ["session.start", "session.compact", "tool.before"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** Hosts that receive compact/resume hook deposits via init/update (#2113). */
+export declare const COMPACT_HOOK_HOSTS: readonly ["claude", "grok", "cursor"];
+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" | "not-direct-write" | "invalid-input" | "ritual-not-ready" | "scope-not-ready" | "write-propose-ready" | "write-ready";
+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 interface HookDecision {
     readonly verdict: HookVerdict;
     readonly code: HookDecisionCode;
@@ -28,6 +35,8 @@ export interface HookDispatchInput {
     readonly projectRoot: string;
     readonly payload: unknown;
     readonly payloadContext?: HookPayloadContext;
+    /** Injected for tests; defaults to `process.env`. */
+    readonly environ?: NodeJS.ProcessEnv;
 }
 export interface HookPolicySeams {
     readonly inspectRitual?: (projectRoot: string) => VerifyResult;
@@ -37,6 +46,12 @@ export interface HookPolicySeams {
         stdout: string;
         stderr: string;
     };
+    readonly markCompactStale?: (projectRoot: string) => {
+        changed: boolean;
+        statePath: string;
+        message: string;
+    };
+    readonly loadRuntimeAuthority?: (projectRoot: string) => RuntimeAuthorityPolicy;
 }
 export declare function hookPayloadTopLevelKeys(payload: unknown): string[];
 export declare function hookToolName(payload: unknown, host?: HookHost): string | null;

package/dist/hooks/dispatcher.js

@@ -1,12 +1,20 @@
 import { relative, resolve, sep } from "node:path";
 import { hasArtifactSuffix } from "../layout/resolve.js";
+import { evaluateRuntimeAuthorityDirectWrite, 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 } from "./tools.js";
-export { DIRECT_WRITE_TOOL_NAMES, isDirectWriteTool } from "./tools.js";
+import { isDirectWriteTool, 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 const HOOK_HOSTS = ["claude", "grok", "cursor", "codex"];
-export const HOOK_EVENTS = ["session.start", "tool.before"];
+export const HOOK_EVENTS = ["session.start", "session.compact", "tool.before"];
+/** Hosts that receive compact/resume hook deposits via init/update (#2113). */
+export const COMPACT_HOOK_HOSTS = ["claude", "grok", "cursor"];
+/** Hosts without a native compact hook surface — deposit skips cleanly (#2113). */
+export const COMPACT_HOOK_SKIP_HOSTS = ["codex"];
 function record(value) {
     return value !== null && typeof value === "object" && !Array.isArray(value)
         ? value
@@ -167,7 +175,7 @@ export function isHookHost(value) {
 export function isHookEvent(value) {
     return HOOK_EVENTS.includes(value);
 }
-function deny(input, code, toolName, message) {
+function deny(input, code, toolName, message, scopePath = null) {
     return {
         verdict: "deny",
         code,
@@ -176,12 +184,144 @@ function deny(input, code, toolName, message) {
         toolName,
         projectRoot: resolve(input.projectRoot),
         message,
-        scopePath: null,
+        scopePath,
+    };
+}
+function runtimeAuthorityForDirectWrite(input, toolName, seams, scopePath) {
+    const projectRoot = resolve(input.projectRoot);
+    let policy;
+    try {
+        policy = (seams.loadRuntimeAuthority ?? loadRuntimeAuthorityFromProject)(projectRoot);
+    }
+    catch {
+        // Fail-open on policy load crash — host behavior; ritual/scope gates already passed.
+        return null;
+    }
+    const writeTarget = hookWriteTargetPath(input.payload);
+    const relPath = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
+    const verdict = evaluateRuntimeAuthorityDirectWrite({ policy, relPathPosix: relPath });
+    if (verdict.allowed)
+        return null;
+    return deny(input, verdict.code ?? "runtime-policy-deny-path", toolName, verdict.reason ?? "Directive denied this direct write under runtime authority policy.", scopePath);
+}
+function inspectMutationGates(input, toolName, seams, options) {
+    const projectRoot = resolve(input.projectRoot);
+    let ritual;
+    try {
+        ritual = (seams.inspectRitual ??
+            ((root) => inspectSessionRitual(root, { tier: "gated", posture: "mutation" })))(projectRoot);
+    }
+    catch (cause) {
+        return deny(input, "ritual-not-ready", toolName, `Directive could not inspect the gated session ritual: ${String(cause)}. ` +
+            "Run `deft session:start`, then `deft verify:session-ritual -- --tier=gated`.");
+    }
+    if (ritual.code !== 0) {
+        return deny(input, "ritual-not-ready", toolName, `Directive denied ${toolName}: ${ritual.message} ` +
+            "Recovery: run `deft session:start`, then " +
+            "`deft verify:session-ritual -- --tier=gated`.");
+    }
+    if (options.proposedLifecycleExempt) {
+        const writeTarget = hookWriteTargetPath(input.payload);
+        if (isProposedLifecycleWrite(projectRoot, writeTarget)) {
+            const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, null);
+            if (runtimeDeny !== null)
+                return runtimeDeny;
+            return {
+                verdict: "allow",
+                code: "write-propose-ready",
+                event: input.event,
+                host: input.host,
+                toolName,
+                projectRoot,
+                message: `Directive write gate allowed ${toolName} for a proposed lifecycle xBRIEF ` +
+                    "(planning write; active scope not required).",
+                scopePath: null,
+            };
+        }
+    }
+    let scope;
+    try {
+        scope = (seams.inspectScope ?? inspectActiveScope)(projectRoot);
+    }
+    catch (cause) {
+        scope = { ready: false, path: null, message: String(cause) };
+    }
+    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}`);
+    }
+    const allowCode = isSpawnTool(toolName) ? "spawn-ready" : "write-ready";
+    if (!isSpawnTool(toolName)) {
+        const runtimeDeny = runtimeAuthorityForDirectWrite(input, toolName, seams, scope.path);
+        if (runtimeDeny !== null)
+            return runtimeDeny;
+    }
+    return {
+        verdict: "allow",
+        code: allowCode,
+        event: input.event,
+        host: input.host,
+        toolName,
+        projectRoot,
+        message: `Directive ${isSpawnTool(toolName) ? "spawn" : "write"} gate passed for ${toolName}.`,
+        scopePath: scope.path,
     };
 }
 /** Decide a normalized event using only the P0 direct-write policy. */
 export function decideHook(input, seams = {}) {
     const projectRoot = resolve(input.projectRoot);
+    if (input.event === "session.compact") {
+        try {
+            const result = (seams.markCompactStale ?? markRitualStaleAfterCompact)(projectRoot);
+            if (!result.changed) {
+                return {
+                    verdict: "allow",
+                    code: "session-compact-noop",
+                    event: input.event,
+                    host: input.host,
+                    toolName: null,
+                    projectRoot,
+                    message: result.message,
+                    scopePath: null,
+                };
+            }
+            return {
+                verdict: "allow",
+                code: "session-compact-rearm",
+                event: input.event,
+                host: input.host,
+                toolName: null,
+                projectRoot,
+                message: result.message,
+                scopePath: null,
+            };
+        }
+        catch (cause) {
+            return {
+                verdict: "allow",
+                code: "session-compact-rearm-degraded",
+                event: input.event,
+                host: input.host,
+                toolName: null,
+                projectRoot,
+                message: "Directive compact re-arm bookkeeping failed on its non-blocking path: " +
+                    `${String(cause)}`,
+                scopePath: null,
+            };
+        }
+    }
     if (input.event === "session.start") {
         try {
             const result = (seams.sessionStart ?? runSessionStartHookWrite)(projectRoot);
@@ -231,74 +371,45 @@ export function decideHook(input, seams = {}) {
             context: input.payloadContext,
         }));
     }
-    if (!isDirectWriteTool(toolName)) {
-        return {
-            verdict: "allow",
-            code: "not-direct-write",
-            event: input.event,
-            host: input.host,
-            toolName,
-            projectRoot,
-            message: `${toolName} is outside the P0 direct-write enforcement slice.`,
-            scopePath: null,
-        };
-    }
-    let ritual;
-    try {
-        ritual = (seams.inspectRitual ??
-            ((root) => inspectSessionRitual(root, { tier: "gated", posture: "mutation" })))(projectRoot);
-    }
-    catch (cause) {
-        return deny(input, "ritual-not-ready", toolName, `Directive could not inspect the gated session ritual: ${String(cause)}. ` +
-            "Run `deft session:start`, then `deft verify:session-ritual -- --tier=gated`.");
+    const environ = input.environ ?? process.env;
+    const readOnly = isReadOnlyHookContext(input.payload, environ);
+    if (readOnly && isDirectWriteTool(toolName)) {
+        return deny(input, "read-only-deny", toolName, `Directive denied ${toolName}: read-only explore posture blocks direct writes. ` +
+            'Use Grok `default_capability_mode = "read-only"` for role-based explore agents, ' +
+            "or set explore subagent_type / DEFT_HOOK_READ_ONLY=1 when the harness supports it.");
     }
-    if (ritual.code !== 0) {
-        return deny(input, "ritual-not-ready", toolName, `Directive denied ${toolName}: ${ritual.message} ` +
-            "Recovery: run `deft session:start`, then " +
-            "`deft verify:session-ritual -- --tier=gated`.");
+    if (isSpawnTool(toolName)) {
+        if (readOnly && !isExploreSpawn(input.payload)) {
+            return deny(input, "read-only-deny", toolName, `Directive denied ${toolName}: read-only posture blocks implementation sub-agent spawns. ` +
+                "Use subagent_type explore for read-only research spawns.");
+        }
+        if (isExploreSpawn(input.payload)) {
+            return {
+                verdict: "allow",
+                code: "spawn-explore-ready",
+                event: input.event,
+                host: input.host,
+                toolName,
+                projectRoot,
+                message: `Directive allowed explore ${toolName} spawn without implementation gates.`,
+                scopePath: null,
+            };
+        }
+        return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: false });
     }
-    const writeTarget = hookWriteTargetPath(input.payload);
-    if (isProposedLifecycleWrite(projectRoot, writeTarget)) {
+    if (!isDirectWriteTool(toolName)) {
         return {
             verdict: "allow",
-            code: "write-propose-ready",
+            code: "not-direct-write",
             event: input.event,
             host: input.host,
             toolName,
             projectRoot,
-            message: `Directive write gate allowed ${toolName} for a proposed lifecycle xBRIEF ` +
-                "(planning write; active scope not required).",
+            message: `${toolName} is outside the P0 direct-write/spawn enforcement slice.`,
             scopePath: null,
         };
     }
-    let scope;
-    try {
-        scope = (seams.inspectScope ?? inspectActiveScope)(projectRoot);
-    }
-    catch (cause) {
-        scope = { ready: false, path: null, message: String(cause) };
-    }
-    if (!scope.ready) {
-        const relTarget = writeTarget !== null ? toProjectRelativePosix(projectRoot, writeTarget) : null;
-        const proposedPathHint = 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, " +
-                "or Write a new proposal to xbrief/proposed/*.xbrief.json (planning exemption).";
-        return deny(input, "scope-not-ready", toolName, `Directive denied ${toolName}: ${scope.message}${proposedPathHint}`);
-    }
-    return {
-        verdict: "allow",
-        code: "write-ready",
-        event: input.event,
-        host: input.host,
-        toolName,
-        projectRoot,
-        message: `Directive write gate passed for ${toolName}.`,
-        scopePath: scope.path,
-    };
+    return inspectMutationGates(input, toolName, seams, { proposedLifecycleExempt: true });
 }
 /** Render only authoritative denials; allow preserves the host's own permission flow. */
 export function renderHostDecision(host, decision) {

package/dist/hooks/readonly.d.ts

@@ -0,0 +1,7 @@
+/** Best-effort read-only explore signal from host payload (#1185). */
+export declare function hookReadOnlyFromPayload(payload: unknown): boolean;
+/** Read-only hook context: env override or host payload marker (#1185). */
+export declare function isReadOnlyHookContext(payload: unknown, environ?: NodeJS.ProcessEnv): boolean;
+/** Explore sub-agent spawns are exempt from the implementation gate stack (#1185). */
+export declare function isExploreSpawn(payload: unknown): boolean;
+//# sourceMappingURL=readonly.d.ts.map

package/dist/hooks/readonly.js

@@ -0,0 +1,83 @@
+import { READ_ONLY_HOOK_ENV } from "./tools.js";
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+function record(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function fieldString(input, key) {
+    const value = input[key];
+    if (typeof value === "string" && value.trim().length > 0)
+        return value.trim();
+    return null;
+}
+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));
+}
+function envTruthy(environ, name) {
+    return TRUTHY.has((environ[name] ?? "").trim().toLowerCase());
+}
+function isReadOnlyCapability(value) {
+    if (value === null)
+        return false;
+    const normalized = value.toLowerCase().replace(/[_\s-]/g, "");
+    return normalized === "readonly";
+}
+/** Best-effort read-only explore signal from host payload (#1185). */
+export function hookReadOnlyFromPayload(payload) {
+    const input = record(payload);
+    if (input === null)
+        return false;
+    const toolInput = toolInputRecord(input) ?? input;
+    const capability = fieldString(toolInput, "capability_mode") ??
+        fieldString(toolInput, "capabilityMode") ??
+        fieldString(toolInput, "default_capability_mode") ??
+        fieldString(toolInput, "defaultCapabilityMode") ??
+        fieldString(input, "capability_mode") ??
+        fieldString(input, "capabilityMode") ??
+        fieldString(input, "default_capability_mode") ??
+        fieldString(input, "defaultCapabilityMode");
+    if (isReadOnlyCapability(capability))
+        return true;
+    const posture = fieldString(toolInput, "posture") ??
+        fieldString(input, "posture") ??
+        fieldString(input, "session_posture") ??
+        fieldString(input, "sessionPosture");
+    if (isReadOnlyCapability(posture))
+        return true;
+    if (toolInput.readOnly === true || toolInput.read_only === true)
+        return true;
+    if (input.readOnly === true || input.read_only === true)
+        return true;
+    return false;
+}
+/** Read-only hook context: env override or host payload marker (#1185). */
+export function isReadOnlyHookContext(payload, environ = process.env) {
+    if (envTruthy(environ, READ_ONLY_HOOK_ENV))
+        return true;
+    return hookReadOnlyFromPayload(payload);
+}
+/** Explore sub-agent spawns are exempt from the implementation gate stack (#1185). */
+export function isExploreSpawn(payload) {
+    const input = record(payload);
+    if (input === null)
+        return false;
+    const toolInput = toolInputRecord(input) ?? input;
+    const subagentType = fieldString(toolInput, "subagent_type") ??
+        fieldString(toolInput, "subagentType") ??
+        fieldString(input, "subagent_type") ??
+        fieldString(input, "subagentType");
+    if (subagentType?.toLowerCase() === "explore")
+        return true;
+    const workerRole = fieldString(toolInput, "worker_role") ??
+        fieldString(toolInput, "workerRole") ??
+        fieldString(input, "worker_role") ??
+        fieldString(input, "workerRole");
+    return workerRole?.toLowerCase() === "explore";
+}
+//# sourceMappingURL=readonly.js.map

package/dist/hooks/tools.d.ts

@@ -1,4 +1,11 @@
 /** Host spellings that install-time matchers and runtime classification share. */
 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"];
+/** 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;
+export declare const DIRECT_WRITE_HOOK_MATCHER: string;
+export declare const SPAWN_HOOK_MATCHER: string;
 //# sourceMappingURL=tools.d.ts.map

package/dist/hooks/tools.js

@@ -13,11 +13,27 @@ export const DIRECT_WRITE_TOOL_NAMES = [
     "ApplyPatch",
     "apply_patch",
 ];
+/** PreToolUse spawn / sub-agent dispatch tools (#1185 / #2437). */
+export const SPAWN_TOOL_NAMES = [
+    "Task",
+    "SubagentStart",
+    "spawn_subagent",
+    "start_agent",
+    "CreateAgent",
+];
+/** Env override forcing hook-level read-only write denial (#1185). */
+export const READ_ONLY_HOOK_ENV = "DEFT_HOOK_READ_ONLY";
 function normalizedToolName(toolName) {
     return toolName.toLowerCase().replace(/[^a-z0-9]/g, "");
 }
 const DIRECT_WRITE_TOOLS = new Set(DIRECT_WRITE_TOOL_NAMES.map(normalizedToolName));
+const SPAWN_TOOLS = new Set(SPAWN_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));
+}
+export const DIRECT_WRITE_HOOK_MATCHER = DIRECT_WRITE_TOOL_NAMES.join("|");
+export const SPAWN_HOOK_MATCHER = SPAWN_TOOL_NAMES.join("|");
 //# sourceMappingURL=tools.js.map

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

@@ -1,15 +1,18 @@
 import type { HookHost } from "../hooks/dispatcher.js";
 import type { InitDepositIo } from "./constants.js";
-export declare const DIRECT_WRITE_HOOK_MATCHER: string;
+export { DIRECT_WRITE_HOOK_MATCHER, SPAWN_HOOK_MATCHER } from "../hooks/tools.js";
 export declare const 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"];
 export type AgentHookPath = (typeof AGENT_HOOK_PATHS)[number];
 export type AgentHookRegistrationStatus = "healthy" | "missing" | "drifted";
+/** Whether the host receives a compact/resume hook deposit (#2113). */
+export type AgentHookCompactSupport = "deposited" | "unsupported";
 export interface AgentHookInspection {
     readonly host: HookHost;
     readonly path: AgentHookPath;
     readonly status: AgentHookRegistrationStatus;
     readonly detail: string;
+    readonly compactSupport: AgentHookCompactSupport;
 }
 export interface AgentHookDepositResult {
     readonly changed: boolean;