@deftai/directive-core 0.79.4 → 0.81.0

package/dist/doctor/checks.d.ts

@@ -39,6 +39,12 @@ export declare const STALE_VBRIEF_CORE_SCHEMA_REL: string;
  * `directive update` instead. Advisory only (exit-exempt).
  */
 export declare function checkStaleXbriefSchemaDeposit(projectRoot: string, seams?: CheckSeams): CheckResult;
+/**
+ * #2591: advisory hint when a TypeScript project pins bare `typescript@7` alongside
+ * typescript-eslint without the `@typescript/typescript6` alias. Exit-exempt (like
+ * gitignore-coverage) — adoption guidance, not a broken install.
+ */
+export declare function checkTypescript7SideBySide(projectRoot: string, seams?: CheckSeams): CheckResult;
 /**
  * #2206: check that the consumer `.gitignore` carries the canonical Deft baseline
  * entries. Advisory (exit-exempt) because missing entries are an adoption risk, not

package/dist/doctor/checks.js

@@ -523,6 +523,142 @@ export function checkStaleXbriefSchemaDeposit(projectRoot, seams = {}) {
         },
     };
 }
+const TS7_SIDE_BY_SIDE_CHECK = "typescript-7-side-by-side";
+function depKeyIsTypescriptEslint(key) {
+    return key === "typescript-eslint" || key.startsWith("@typescript-eslint/");
+}
+function depKeysIncludeTypescriptEslint(keys) {
+    return keys.some(depKeyIsTypescriptEslint);
+}
+function depKeysIncludeEslint(keys) {
+    return keys.includes("eslint");
+}
+function typescriptValueIs7Bound(value) {
+    const v = value.trim();
+    if (!v || v.includes("@typescript/typescript6")) {
+        return false;
+    }
+    if (/npm:typescript@(?:[\^~>=<]*|\d*)7/i.test(v)) {
+        return true;
+    }
+    if (/^[\^~>=<]*7(?:\.\d|$)/.test(v)) {
+        return true;
+    }
+    if (/^7\.\d/.test(v)) {
+        return true;
+    }
+    return false;
+}
+function resolveTypescriptDepValue(deps, devDeps) {
+    if (typeof devDeps.typescript === "string") {
+        return devDeps.typescript;
+    }
+    if (typeof deps.typescript === "string") {
+        return deps.typescript;
+    }
+    return null;
+}
+/**
+ * #2591: advisory hint when a TypeScript project pins bare `typescript@7` alongside
+ * typescript-eslint without the `@typescript/typescript6` alias. Exit-exempt (like
+ * gitignore-coverage) — adoption guidance, not a broken install.
+ */
+export function checkTypescript7SideBySide(projectRoot, seams = {}) {
+    const packageJsonPath = join(projectRoot, "package.json");
+    const text = readText(packageJsonPath, seams);
+    if (text === null) {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "skip",
+            detail: "package.json not found; nothing to inspect for TypeScript side-by-side layout.",
+            data: { package_json_path: packageJsonPath },
+        };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "skip",
+            detail: "package.json is unreadable; skipping TypeScript side-by-side check.",
+            data: { package_json_path: packageJsonPath },
+        };
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "skip",
+            detail: "package.json has no dependency sections; skipping TypeScript side-by-side check.",
+            data: { package_json_path: packageJsonPath },
+        };
+    }
+    const record = parsed;
+    const deps = typeof record.dependencies === "object" && record.dependencies !== null
+        ? record.dependencies
+        : {};
+    const devDeps = typeof record.devDependencies === "object" && record.devDependencies !== null
+        ? record.devDependencies
+        : {};
+    const depKeys = [...Object.keys(deps), ...Object.keys(devDeps)];
+    if (depKeys.length === 0) {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "skip",
+            detail: "package.json has no dependency sections; skipping TypeScript side-by-side check.",
+            data: { package_json_path: packageJsonPath },
+        };
+    }
+    if (!depKeysIncludeTypescriptEslint(depKeys)) {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "pass",
+            detail: "No typescript-eslint packages declared; TypeScript 7 side-by-side alias not required.",
+            data: { package_json_path: packageJsonPath },
+        };
+    }
+    if (!depKeysIncludeEslint(depKeys)) {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "pass",
+            detail: "eslint is not declared; TypeScript 7 side-by-side alias not required.",
+            data: { package_json_path: packageJsonPath },
+        };
+    }
+    const typescriptValue = resolveTypescriptDepValue(deps, devDeps);
+    if (typescriptValue === null) {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "pass",
+            detail: "No typescript dependency declared; TypeScript 7 side-by-side alias not required.",
+            data: { package_json_path: packageJsonPath },
+        };
+    }
+    if (!typescriptValueIs7Bound(typescriptValue)) {
+        return {
+            name: TS7_SIDE_BY_SIDE_CHECK,
+            status: "pass",
+            detail: "typescript is not pinned to 7.x (or uses the @typescript/typescript6 alias); side-by-side layout not required.",
+            data: {
+                package_json_path: packageJsonPath,
+                typescript: typescriptValue,
+            },
+        };
+    }
+    return {
+        name: TS7_SIDE_BY_SIDE_CHECK,
+        status: "fail",
+        detail: "typescript resolves to 7.x without the @typescript/typescript6 alias while typescript-eslint and eslint are present. " +
+            "Until TS 7.1, use the side-by-side alias pattern in languages/typescript.md § TypeScript 7 side-by-side (pre-7.1) " +
+            "(Cartograph #111: keep typescript on npm:@typescript/typescript6 and install TS 7 under @typescript/native).",
+        data: {
+            package_json_path: packageJsonPath,
+            typescript: typescriptValue,
+            suggested_fix: "languages/typescript.md#typescript-7-side-by-side-pre-71",
+        },
+    };
+}
 /**
  * #2206: check that the consumer `.gitignore` carries the canonical Deft baseline
  * entries. Advisory (exit-exempt) because missing entries are an adoption risk, not
@@ -580,6 +716,7 @@ export function deriveExitCode(checks, errors) {
         "manifest-version-reportable",
         "gitignore-coverage",
         "stale-xbrief-schema-deposit",
+        "typescript-7-side-by-side",
     ]);
     if (errors.length > 0 || checks.some((c) => c.status === "error")) {
         return 2;
@@ -621,6 +758,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
         checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
         checks.push(checkStaleXbriefSchemaDeposit(projectRoot, seams));
         checks.push(checkGitignoreCoverage(projectRoot, seams));
+        checks.push(checkTypescript7SideBySide(projectRoot, seams));
         return {
             projectRoot,
             installRoot: null,
@@ -638,6 +776,7 @@ export function runChecksImpl(projectRoot, seams = {}) {
     checks.push(checkCanonicalVendoredNpmSignpost(projectRoot, seams));
     checks.push(checkStaleXbriefSchemaDeposit(projectRoot, seams));
     checks.push(checkGitignoreCoverage(projectRoot, seams));
+    checks.push(checkTypescript7SideBySide(projectRoot, seams));
     return {
         projectRoot,
         installRoot,

package/dist/doctor/main.js

@@ -424,7 +424,8 @@ function runInstallIntegrityChecks(projectRoot, sink, addFinding, seams) {
                 name === "canonical-vendored-npm-signpost" ||
                 name === "manifest-version-reportable" ||
                 name === "gitignore-coverage" ||
-                name === "stale-xbrief-schema-deposit") &&
+                name === "stale-xbrief-schema-deposit" ||
+                name === "typescript-7-side-by-side") &&
                 status === "fail") {
                 sink.warn(`${name}: ${detail}`);
                 addFinding({

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