@deftai/directive-runtime 0.129.0 → 0.129.2

package/.githooks/_directive-run.sh

@@ -1,6 +1,7 @@
 #!/usr/bin/env sh
-# Package-relative Directive git-hook helper (AC9.9).
+# Package-relative Directive git-hook helper (AC9.9 / AC9.12 / #5994).
 # Sourced by pre-commit/pre-push; defines run_directive.
+# F1 order: disable → missing pin (project PM) → pin bin.js.
 if [ -z "${REPO_ROOT:-}" ]; then
   REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 fi
@@ -8,23 +9,19 @@ if [ -z "$REPO_ROOT" ]; then
   echo "directive hooks: unable to resolve repo root." >&2
   exit 1
 fi
-RUNTIME_BIN="$REPO_ROOT/node_modules/@deftai/directive-runtime/dist/bin.js"
-if [ ! -f "$RUNTIME_BIN" ]; then
-  echo "directive hooks: missing $RUNTIME_BIN" >&2
-  echo "Recovery: npm i -g @deftai/directive, then directive install --repair" >&2
-  exit 1
-fi
 run_directive() {
-  # #3039 / #5543: root local kill-switch — skip CLI spawn when flag is present,
-  # not a symlink, and not tracked by git (tracked flag must not disable clones).
+  # #3039 / #5543 / #5994 F1: disable BEFORE requiring pin bin.js; quiet skip.
   _kill="$REPO_ROOT/.deft-directive-disable"
   if [ -f "$_kill" ] && [ ! -L "$_kill" ]; then
     if ! git -C "$REPO_ROOT" ls-files --error-unmatch -- .deft-directive-disable >/dev/null 2>&1; then
-      echo "Directive is DISABLED for this project via root .deft-directive-disable (test/local kill-switch)." >&2
-      echo "Git hooks skipping Directive CLI spawn (#5543 / #3039). Deposit may remain." >&2
-      echo "Recovery: rm .deft-directive-disable && start a new agent session." >&2
       return 0
     fi
   fi
+  RUNTIME_BIN="$REPO_ROOT/node_modules/@deftai/directive-runtime/dist/bin.js"
+  if [ ! -f "$RUNTIME_BIN" ]; then
+    echo "directive hooks: missing $RUNTIME_BIN" >&2
+    echo "Directive hooks: missing node_modules/@deftai/directive-runtime. Run npm install or pnpm install (or yarn) in this project." >&2
+    exit 1
+  fi
   node "$RUNTIME_BIN" "$@"
 }

package/.githooks/pre-push

@@ -5,8 +5,4 @@ REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)" || exit 1
 . "$REPO_ROOT/.githooks/_directive-run.sh"
 run_directive verify:branch --project-root "$REPO_ROOT" || exit $?
 # Enrolled bound pre-PR arm: sole-stdin (do not redirect shared run_directive to /dev/null)
-# Pins older than #5804 lack --push-admit: keep the pre-#5804 hook there (verify:branch only).
-_pre_pr_help="$(run_directive pre-pr:run --help </dev/null 2>&1)" || exit $?
-case "$_pre_pr_help" in
-  *--push-admit*) run_directive pre-pr:run --push-admit --project-root "$REPO_ROOT" || exit $? ;;
-esac
+run_directive pre-pr:run --push-admit --project-root "$REPO_ROOT" || exit $?

package/UPGRADING.md

@@ -79,7 +79,7 @@ npm install -g --allow-scripts=<pkg,...> <package>
 
 ### Framework monorepo contributors
 
-Install source of truth for this repo is **pnpm** (`packageManager` field; CI uses `pnpm install --frozen-lockfile`). Install-script builds are gated by `pnpm-workspace.yaml` **`allowBuilds`** (currently `esbuild: true`). Do **not** treat `npm approve-scripts` under the pnpm virtual store as monorepo SoT.
+Install source of truth for this repo is **pnpm** (`packageManager` field; CI uses `pnpm install --frozen-lockfile`). Install-script builds are gated by `pnpm-workspace.yaml` **`allowBuilds`** (currently `esbuild: true` where needed). **`allowBuilds` is PM-owned**: Directive install/upgrade uses the package manager for `package.json` / lockfile pin ops and does **not** hand-edit `allowBuilds`. If pnpm fails with `ERR_PNPM_IGNORED_BUILDS`, recover with `pnpm approve-builds` or set a real `true`/`false` under `allowBuilds` — do **not** commit pnpm's interactive placeholder text. Pin/add paths already pass `--ignore-scripts` so ordinary consumer upgrades should not need a runtime `allowBuilds` entry. Do **not** treat `npm approve-scripts` under the pnpm virtual store as monorepo SoT.
 
 ### Git / remote package sources and publish
 
@@ -456,7 +456,7 @@ import schema from "@deftai/directive-types/schemas/xbrief-core-0.8.schema.json"
 
 **Supported public API:** `@deftai/directive-types` and its published schema subpaths only. **`@deftai/directive-core` is published for npm dependency resolution but is not a supported library surface** — use the `deft` / `directive` CLI for behavior.
 
-**Schema source of truth:** `content/vbrief/schemas/vbrief-core.schema.json` in the directive repo. The types package mirrors it to `packages/types/schemas/` at build time; `deft` install also deposits schemas under project-root `xbrief/schemas/`. When in doubt, treat the directive repo canonical file as authoritative and refresh mirrors with `deft update` (install) or `@deftai/directive-types` (npm).
+**Schema source of truth (OVPR):** the pinned runtime ships schemas under `node_modules/@deftai/directive-runtime/vbrief/schemas/` (current write schema: `xbrief-core-0.8.schema.json`). The types package publishes the same artifacts as `@deftai/directive-types/schemas/…`. Framework source authors at `content/vbrief/schemas/`. Install does **not** deposit project-root `xbrief/schemas/`. Refresh via `directive upgrade` (pin) or `@deftai/directive-types` (npm).
 
 ### `deft migrate` vs pre-v0.20 document-model migration
 

package/dist/doctor-diagnose.d.ts

@@ -8,6 +8,11 @@ export { DEFT_DOCTOR_HOOK_DIAGNOSTIC };
 export declare const GIT_PRECONDITION_RECOVERY_GUIDANCE = "git init, then directive install --repair";
 /** Readiness detail when wiring-ready is withheld solely because there is no .git. */
 export declare const GIT_PRECONDITION_READINESS_DETAIL = "incomplete install \u2014 wiring-ready withheld until git init (hooksPath not activatable)";
+/**
+ * #5798 — wiring-only residual (pin/install/readiness already ok).
+ * Names Taskfile/probe surface; owned wiring damage → repair, never npm i -g hammer.
+ */
+export declare const WIRING_RECOVERY_GUIDANCE = "inspect Taskfile.yml / Directive wiring targets (or probe); for owned wiring damage: directive install --repair";
 /** Patterns that must never appear as doctor remedies (AC12.5–12.7 / AC9.11). */
 export declare const FORBIDDEN_DOCTOR_REMEDY_PATTERNS: readonly RegExp[];
 export interface DoctorSurface {
@@ -34,11 +39,11 @@ export interface DoctorDiagnosis {
     readonly failClosed: boolean;
     readonly dataStatus: DataStatusValue;
     /**
-     * Install/wiring recovery guidance, or F-010 git-precondition recovery.
-     * Null when healthy or schema-only.
+     * Install-class (AC9.7), wiring-only (#5798 WIRING_RECOVERY_GUIDANCE), or
+     * F-010 git-precondition recovery. Null when healthy or schema-only.
      */
     readonly remedy: string | null;
-    /** Schema/data migration remedy; never `install --repair`. */
+    /** Schema/data migration remedy; never the AC9.7 global-install hammer. */
     readonly schemaRemedy: "directive upgrade" | null;
     /**
      * F-010: set when pin/lock/installed/GENERATION/wiring are ok but readiness is

package/dist/doctor-diagnose.js

@@ -6,6 +6,7 @@
  */
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
+import { isHostHookOuterCommand } from "../vendor/directive-core/dist/init-deposit/host-hook-outer.js";
 import { checkFullInSync, DEFT_DOCTOR_HOOK_DIAGNOSTIC, INSTALLATION_RECOVERY_GUIDANCE, RUNTIME_PACKAGE_PATH_PREFIX, } from "../vendor/directive-core/dist/install-health/index.js";
 import { readProjectDataStatus } from "./data-status.js";
 export { DEFT_DOCTOR_HOOK_DIAGNOSTIC };
@@ -16,6 +17,11 @@ export { DEFT_DOCTOR_HOOK_DIAGNOSTIC };
 export const GIT_PRECONDITION_RECOVERY_GUIDANCE = "git init, then directive install --repair";
 /** Readiness detail when wiring-ready is withheld solely because there is no .git. */
 export const GIT_PRECONDITION_READINESS_DETAIL = "incomplete install — wiring-ready withheld until git init (hooksPath not activatable)";
+/**
+ * #5798 — wiring-only residual (pin/install/readiness already ok).
+ * Names Taskfile/probe surface; owned wiring damage → repair, never npm i -g hammer.
+ */
+export const WIRING_RECOVERY_GUIDANCE = "inspect Taskfile.yml / Directive wiring targets (or probe); for owned wiring damage: directive install --repair";
 /** Patterns that must never appear as doctor remedies (AC12.5–12.7 / AC9.11). */
 export const FORBIDDEN_DOCTOR_REMEDY_PATTERNS = [
     /\balign-pin\b/i,
@@ -43,7 +49,7 @@ function schemaSurface(dataStatus) {
     return { ok: false, detail: "project data schema diagnosis failed" };
 }
 /**
- * Cheap read-only check that committed hook/skill wiring uses package-relative form.
+ * Cheap read-only check that committed hook/skill wiring uses host `.mjs` outer or package-relative form.
  * Does not spawn hooks; structural only (AC12.3 hook command form / skill pointers).
  */
 function inspectHookAndSkillForm(projectRoot) {
@@ -65,11 +71,13 @@ function inspectHookAndSkillForm(projectRoot) {
         sawHook = true;
         try {
             const text = readFileSync(abs, "utf8");
+            // #5994 / AC9.1: v261027 host `.mjs` outer is the registered form; pin hook-bin is spawned inside.
+            const hasOuter = isHostHookOuterCommand(text);
             const hasPkg = text.includes(prefix) && text.includes("hook-bin");
             const hasLegacy = text.includes(".deft/core/") || /(^|[\s"`'])deft-hook([\s"`']|$)/.test(text);
-            if (hasLegacy || !hasPkg) {
+            if (hasLegacy || !(hasOuter || hasPkg)) {
                 hookOk = false;
-                hookDetail = `${rel} does not use package-relative hook-bin form`;
+                hookDetail = `${rel} does not use host .mjs outer or package-relative hook-bin form`;
                 break;
             }
         }
@@ -208,13 +216,26 @@ function chooseRemedy(sync, dataStatus, projectRoot) {
     if (isNoGitReadinessGap(sync, projectRoot)) {
         return { remedy: GIT_PRECONDITION_RECOVERY_GUIDANCE, schemaRemedy: null };
     }
-    const installBroken = sync.failClosed || !sync.inSync || !sync.predicates.installed.ok || !sync.predicates.pin.ok;
-    // AC12.7: never dual-prescribe upgrade + repair. Install/wiring recovery wins
-    // when both faults are present; schema-only behind → upgrade alone.
-    if (installBroken) {
+    const p = sync.predicates;
+    // Install-class faults only — do NOT fold wiring-only into AC9.7 via !inSync (#5798).
+    const pinInstallBroken = sync.failClosed || !p.pin.ok || !p.installed.ok || !p.lockfile.ok || !p.generation.ok;
+    // Missing readiness (with .git) stays install/repair guidance (acceptance / F-010 peer).
+    const readinessBroken = !p.readiness.ok;
+    const wiringBroken = !p.wiring.ok;
+    const schemaBehind = dataStatus === "migration_needed" || dataStatus === "diagnosis_failed";
+    // AC12.7: AC9.7 global install + schema upgrade must not co-prescribe for install-class red.
+    if (pinInstallBroken || readinessBroken) {
         return { remedy: INSTALLATION_RECOVERY_GUIDANCE, schemaRemedy: null };
     }
-    if (dataStatus === "migration_needed" || dataStatus === "diagnosis_failed") {
+    // Wiring-only (good pin/install/readiness): failure-shaped map — Taskfile/probe, not npm i -g.
+    if (wiringBroken) {
+        return {
+            remedy: WIRING_RECOVERY_GUIDANCE,
+            // Distinct surfaces may list both (#5798 multi-surface); not the AC9.7+upgrade dual ban.
+            schemaRemedy: schemaBehind ? "directive upgrade" : null,
+        };
+    }
+    if (schemaBehind) {
         return { remedy: null, schemaRemedy: "directive upgrade" };
     }
     return { remedy: null, schemaRemedy: null };

package/dist/hook-dispatch.js

@@ -239,7 +239,8 @@ export function run(argv, seams = {}) {
     }
     // Wave 2d / AC8.6: registered hooks self-complete when readiness is missing/stale.
     // Suppressed when DEFT_DOCTOR_HOOK_DIAGNOSTIC is set (AC9.10).
-    maybeSelfCompleteSetup(projectRoot, { fromHook: true });
+    // #5885: thread seams.writeErr so preserved tracked hooks disclose on stderr.
+    maybeSelfCompleteSetup(projectRoot, { fromHook: true, writeErr });
     const environ = mergeHookDispatchEnviron(payload);
     let decision = decideHook({
         host: args.host,

package/dist/pre-pr-run.js

@@ -422,13 +422,15 @@ export function run(argv) {
                 return 2;
             }
             const spec = phaseSpec(phase);
+            // Same root rule as push-admit: one report path for observe and satisfy.
+            const projectRoot = args.projectRoot?.trim() || process.cwd();
             const d = observeCommandPhase(store, args.runId, {
                 phaseId: phase,
                 command: args.command.length > 0 ? args.command : (spec.command ?? ""),
                 exitCode: args.exitCode,
                 inputHash: args.inputHash ?? rec?.inputHash ?? "",
                 skipReason: args.skipReason,
-            });
+            }, { projectRoot });
             emit(args.json, d, d.message, !d.ok);
             return d.ok ? 0 : 1;
         }
@@ -508,7 +510,12 @@ export function run(argv) {
             process.stderr.write("pre_pr_run: --complete requires --run-id\n");
             return 2;
         }
-        const d = completeRun(store, controllerPublisher(), args.runId);
+        // #5804 / #5994: projectRoot is required so completeRun can stamp
+        // pushBinding.reviewedDeletedPaths from base..head.
+        const projectRoot = args.projectRoot?.trim() || process.cwd();
+        const d = completeRun(store, controllerPublisher(), args.runId, undefined, {
+            projectRoot,
+        });
         emit(args.json, d, d.message, !d.ok);
         return d.ok ? 0 : 1;
     }

package/dist/self-complete.d.ts

@@ -5,6 +5,8 @@ import { type SetupResult } from "./setup.js";
  * Doctor sets this before spawning committed hook probes.
  */
 export declare const DEFT_DOCTOR_HOOK_DIAGNOSTIC = "DEFT_DOCTOR_HOOK_DIAGNOSTIC";
+/** Test-only: clear the process once-guard for preserved disclosure. */
+export declare function resetSelfCompletePreservedDisclosureForTests(): void;
 export type SelfCompleteSkipReason = "fast-path" | "doctor-diagnostic" | "ineligible" | "not-configured" | "fail-closed" | "no-version";
 export interface SelfCompleteResult {
     readonly ran: boolean;
@@ -24,5 +26,7 @@ export declare function maybeSelfCompleteSetup(projectRoot: string, options?: {
     readonly environ?: NodeJS.ProcessEnv;
     /** Hooks are always eligible unless doctor-diagnostic. */
     readonly fromHook?: boolean;
+    /** Stderr sink for preserved tracked-hook disclosure (#5885); never stdout. */
+    readonly writeErr?: (text: string) => void;
 }): SelfCompleteResult;
 //# sourceMappingURL=self-complete.d.ts.map

package/dist/self-complete.js

@@ -23,6 +23,22 @@ import { runSetup } from "./setup.js";
  * Doctor sets this before spawning committed hook probes.
  */
 export const DEFT_DOCTOR_HOOK_DIAGNOSTIC = DOCTOR_DIAGNOSTIC_ENV;
+/** Process once-guard for preserved-hook stderr lines (#5885). */
+const emittedPreservedLines = new Set();
+/** Test-only: clear the process once-guard for preserved disclosure. */
+export function resetSelfCompletePreservedDisclosureForTests() {
+    emittedPreservedLines.clear();
+}
+function disclosePreservedHooks(preserved, writeErr) {
+    if (preserved === undefined || preserved.length === 0)
+        return;
+    for (const line of preserved) {
+        if (emittedPreservedLines.has(line))
+            continue;
+        emittedPreservedLines.add(line);
+        writeErr(`${line}\n`);
+    }
+}
 /** Installation-management and help heads that never trigger self-complete. */
 const INELIGIBLE_HEADS = new Set([
     "install",
@@ -76,6 +92,7 @@ function readOwnRuntimeVersion() {
  */
 export function maybeSelfCompleteSetup(projectRoot, options = {}) {
     const environ = options.environ ?? process.env;
+    const writeErr = options.writeErr ?? ((text) => process.stderr.write(text));
     if (isDoctorDiagnosticEnv(environ)) {
         return { ran: false, skipReason: "doctor-diagnostic", setup: null };
     }
@@ -113,6 +130,7 @@ export function maybeSelfCompleteSetup(projectRoot, options = {}) {
         from: version,
         root: projectRoot,
     });
+    disclosePreservedHooks(setup.preserved, writeErr);
     return { ran: true, skipReason: null, setup };
 }
 //# sourceMappingURL=self-complete.js.map

package/dist/setup-wiring.d.ts

@@ -94,6 +94,11 @@ export declare function formatTrackedHookPreserved(rel: string): string;
 export interface EnsureGitHooksOptions {
     /** Explicit pre-write operator force: replace tracked divergent managed hooks (#5837). */
     readonly forceTrackedReplace?: boolean;
+    /**
+     * Test-only: override the next body for named relative hook paths so fixtures
+     * can reach refuse-to-downgrade under forceTrackedReplace (#5885 / #5804).
+     */
+    readonly testOnlyNextBodyByRel?: Readonly<Record<string, string>>;
 }
 export declare function ensureGitHooks(projectRoot: string, options?: EnsureGitHooksOptions): {
     created: string[];

package/dist/setup-wiring.js

@@ -8,6 +8,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { containedChmod, containedRemove, containedWrite, } from "../vendor/directive-core/dist/fs/contained-write.js";
 import { DIRECT_WRITE_HOOK_MATCHER, KILL_HOOK_MATCHER, MCP_HOOK_MATCHER, SHELL_HOOK_MATCHER, SPAWN_HOOK_MATCHER, } from "../vendor/directive-core/dist/hooks/tools.js";
+import { GROK_PRETOOLUSE_WRAPPER_REL_PATH, HOST_HOOK_MISSING_PIN_PROJECT_PM_GUIDANCE, hostHookOuterCommand, hostHookOuterRelPath, hostHookOuterSha8, hostHookOuterSource, isGrokWrapperCommand, isHostHookOuterCommand, } from "../vendor/directive-core/dist/init-deposit/agent-hooks.js";
 import { INSTALLATION_RECOVERY_GUIDANCE, RUNTIME_PACKAGE_PATH_PREFIX, } from "../vendor/directive-core/dist/install-health/constants.js";
 import { MANAGED_SECTION_CLOSE, MANAGED_SECTION_OPEN_PREFIX, } from "../vendor/directive-core/dist/install-health/index.js";
 import { applyAgentsRefresh } from "../vendor/directive-core/dist/platform/agents-md.js";
@@ -375,25 +376,45 @@ export function ensureOpenClawIntegrations(projectRoot) {
     }
 }
 function hookCommand(host, event) {
-    return `${HOOK_BIN_COMMAND} --host ${host} --event ${event}`;
+    const sha8 = hostHookOuterSha8();
+    return `${hostHookOuterCommand(host, sha8)} --host ${host} --event ${event}`;
 }
 /** Rewrite bare `deft-hook` / legacy `deft hook:dispatch` to package-relative (AC9.2). */
 export function rewriteBareDeftHookCommand(command) {
     const trimmed = command.trim();
-    if (trimmed.startsWith(HOOK_BIN_COMMAND))
+    if (isHostHookOuterCommand(trimmed))
         return command;
+    const hostMatch = trimmed.match(/--host\s+(\w+)/);
+    const eventMatch = trimmed.match(/--event\s+([\w.]+)/);
+    const host = hostMatch?.[1];
+    const event = eventMatch?.[1];
+    const sha8 = hostHookOuterSha8();
+    const toOuter = (h, e) => `${hostHookOuterCommand(h, sha8)} --host ${h} --event ${e}`;
+    // Legacy Grok .sh wrapper → outer
+    if (isGrokWrapperCommand(trimmed) && host && event) {
+        return toOuter(host, event);
+    }
+    if (isGrokWrapperCommand(trimmed)) {
+        return toOuter("grok", "tool.before");
+    }
+    // Direct hook-bin with host/event → outer
+    if (trimmed.includes(HOOK_BIN_COMMAND) && host && event) {
+        return toOuter(host, event);
+    }
     const bare = /^(?:deft-hook|deft\s+hook:dispatch)(\s+.*)?$/;
     const m = trimmed.match(bare);
     if (m) {
         const rest = (m[1] ?? "").trim();
+        if (host && event)
+            return toOuter(host, event);
+        // bare without host/event: leave as package-relative interim only if no host
         return rest.length > 0 ? `${HOOK_BIN_COMMAND} ${rest}` : HOOK_BIN_COMMAND;
     }
-    // Inline occurrences inside longer strings (rare)
-    if (/\bdeft-hook\b/.test(trimmed) && !trimmed.includes(RUNTIME_PREFIX)) {
-        return trimmed.replace(/\bdeft-hook\b/g, HOOK_BIN_COMMAND);
+    if (/\bdeft-hook\b/.test(trimmed) && !isHostHookOuterCommand(trimmed) && host && event) {
+        return toOuter(host, event);
     }
-    if (/\bdeft\s+hook:dispatch\b/.test(trimmed) && !trimmed.includes(RUNTIME_PREFIX)) {
-        return trimmed.replace(/\bdeft\s+hook:dispatch\b/g, HOOK_BIN_COMMAND);
+    if (/\bdeft\s+hook:dispatch\b/.test(trimmed) && host && event) {
+        return toOuter(host, event);
     }
     return command;
 }
@@ -427,7 +448,9 @@ function rewriteCommandsInValue(value) {
     return { value, changed: false };
 }
 function isManagedHookCommand(command) {
-    return (command.includes(HOOK_BIN_COMMAND) ||
+    return (isHostHookOuterCommand(command) ||
+        command.includes(HOOK_BIN_COMMAND) ||
+        isGrokWrapperCommand(command) ||
         /(^|[\s"`'])deft-hook([\s"`']|$)/.test(command) ||
         command.includes("deft hook:dispatch"));
 }
@@ -436,26 +459,47 @@ function object(value) {
         ? value
         : null;
 }
-function nestedManagedGroup(value) {
+function isManagedNestedHookCommand(command, host) {
+    if (host === "grok" && isGrokWrapperCommand(command))
+        return true;
+    return isManagedHookCommand(command) && command.includes(`--host ${host}`);
+}
+/**
+ * Drop managed commands inside a nested group; keep custom hooks and group fields.
+ * Returns null when the group is empty after filtering (or was fully managed).
+ * Non-group entries pass through unchanged.
+ */
+function filterManagedCommandsInNestedGroup(value, host, options = {}) {
     const group = object(value);
     if (group === null || !Array.isArray(group.hooks))
-        return false;
-    return group.hooks.some((h) => {
+        return value;
+    const keptHooks = group.hooks.filter((h) => {
         const hook = object(h);
-        return typeof hook?.command === "string" && isManagedHookCommand(hook.command);
+        if (typeof hook?.command !== "string")
+            return true;
+        if (options.hostAgnostic)
+            return !isManagedHookCommand(hook.command);
+        return !isManagedNestedHookCommand(hook.command, host);
     });
+    if (keptHooks.length === 0)
+        return null;
+    return { ...group, hooks: keptHooks };
 }
 function cursorManagedEntry(value) {
     const entry = object(value);
     return typeof entry?.command === "string" && isManagedHookCommand(entry.command);
 }
+function nestedToolCommand(host, event) {
+    // #5994 / AC9.1: every host/event uses the content-hashed `.mjs` outer.
+    return hookCommand(host, event);
+}
 function nestedGroup(host, event, matcher) {
     return {
         ...(event === "tool.before" && matcher !== undefined ? { matcher } : {}),
         hooks: [
             {
                 type: "command",
-                command: hookCommand(host, event),
+                command: nestedToolCommand(host, event),
                 timeout: event === "tool.before" ? 30 : 5,
             },
         ],
@@ -478,17 +522,9 @@ function stripNestedManaged(existing, host) {
         if (!(key in hooks))
             continue;
         const filtered = Array.isArray(hooks[key])
-            ? hooks[key].filter((e) => {
-                const group = object(e);
-                if (group === null || !Array.isArray(group.hooks))
-                    return true;
-                return !group.hooks.some((h) => {
-                    const hook = object(h);
-                    return (typeof hook?.command === "string" &&
-                        isManagedHookCommand(hook.command) &&
-                        hook.command.includes(`--host ${host}`));
-                });
-            })
+            ? hooks[key]
+                .map((e) => filterManagedCommandsInNestedGroup(e, host))
+                .filter((e) => e !== null)
             : [];
         if (filtered.length > 0)
             nextHooks[key] = filtered;
@@ -525,13 +561,21 @@ function stripCursorManaged(existing) {
     }
     return { ...existing, version: 1, hooks: nextHooks };
 }
+function keepCustomNestedGroups(entries, host) {
+    return entries
+        .map((e) => filterManagedCommandsInNestedGroup(e, host, {
+        // Merge clears any managed identity (incl. Grok wrapper) before redeposit.
+        hostAgnostic: true,
+    }))
+        .filter((e) => e !== null);
+}
 function mergeNestedHost(existing, host, options) {
     const hooks = object(existing.hooks) ?? {};
     const session = Array.isArray(hooks.SessionStart)
-        ? hooks.SessionStart.filter((e) => !nestedManagedGroup(e))
+        ? keepCustomNestedGroups(hooks.SessionStart, host)
         : [];
     const preTool = Array.isArray(hooks.PreToolUse)
-        ? hooks.PreToolUse.filter((e) => !nestedManagedGroup(e))
+        ? keepCustomNestedGroups(hooks.PreToolUse, host)
         : [];
     const nextHooks = {
         ...hooks,
@@ -543,10 +587,10 @@ function mergeNestedHost(existing, host, options) {
     };
     if (options.compact) {
         const preCompact = Array.isArray(hooks.PreCompact)
-            ? hooks.PreCompact.filter((e) => !nestedManagedGroup(e))
+            ? keepCustomNestedGroups(hooks.PreCompact, host)
             : [];
         const postCompact = Array.isArray(hooks.PostCompact)
-            ? hooks.PostCompact.filter((e) => !nestedManagedGroup(e))
+            ? keepCustomNestedGroups(hooks.PostCompact, host)
             : [];
         nextHooks.PreCompact = [...preCompact, nestedGroup(host, "session.compact")];
         nextHooks.PostCompact = [...postCompact, nestedGroup(host, "session.compact")];
@@ -665,11 +709,51 @@ export function ensureHostHooks(projectRoot, hostHooksPolicy = loadHostHooksPoli
         else
             modified.push(spec.rel);
     }
+    // #5994: deposit content-hashed `.mjs` outers; strip legacy Grok `.sh`.
+    const outerSource = hostHookOuterSource();
+    const outerSha8 = hostHookOuterSha8(outerSource);
+    for (const host of ["claude", "grok", "cursor", "codex"]) {
+        const rel = hostHookOuterRelPath(host, outerSha8);
+        const enabled = isHostHookDepositEnabled(host, hostHooksPolicy);
+        if (enabled) {
+            const prior = readText(join(projectRoot, rel));
+            if (prior !== outerSource) {
+                writeContained(projectRoot, rel, outerSource);
+                if (prior === null)
+                    created.push(rel);
+                else
+                    modified.push(rel);
+            }
+        }
+        else if (existsSync(join(projectRoot, rel))) {
+            try {
+                containedRemove({ root: projectRoot, target: rel });
+                modified.push(rel);
+            }
+            catch {
+                /* best-effort strip */
+            }
+        }
+    }
+    const wrapperRel = GROK_PRETOOLUSE_WRAPPER_REL_PATH;
+    if (existsSync(join(projectRoot, wrapperRel))) {
+        try {
+            containedRemove({ root: projectRoot, target: wrapperRel });
+            modified.push(wrapperRel);
+        }
+        catch {
+            /* best-effort strip */
+        }
+    }
     return { created, modified };
 }
+// Taskfile F1 disable-first + project-PM pin miss live in tasks/engine.yml +
+// tasks/engine-invoke.cjs (#5994) — disable-active runs BEFORE pin-bin / is-buildable-source;
+// pin-bin also quiet-exits when disable is active. This GITHOOK_HELPER is the .githooks twin.
 const GITHOOK_HELPER = `#!/usr/bin/env sh
-# Package-relative Directive git-hook helper (AC9.9).
+# Package-relative Directive git-hook helper (AC9.9 / AC9.12 / #5994).
 # Sourced by pre-commit/pre-push; defines run_directive.
+# F1 order: disable → missing pin (project PM) → pin bin.js.
 if [ -z "\${REPO_ROOT:-}" ]; then
   REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null)"
 fi
@@ -677,24 +761,20 @@ if [ -z "$REPO_ROOT" ]; then
   echo "directive hooks: unable to resolve repo root." >&2
   exit 1
 fi
-RUNTIME_BIN="$REPO_ROOT/${RUNTIME_BIN_REL}"
-if [ ! -f "$RUNTIME_BIN" ]; then
-  echo "directive hooks: missing $RUNTIME_BIN" >&2
-  echo "Recovery: ${INSTALLATION_RECOVERY_GUIDANCE}" >&2
-  exit 1
-fi
 run_directive() {
-  # #3039 / #5543: root local kill-switch — skip CLI spawn when flag is present,
-  # not a symlink, and not tracked by git (tracked flag must not disable clones).
+  # #3039 / #5543 / #5994 F1: disable BEFORE requiring pin bin.js; quiet skip.
   _kill="$REPO_ROOT/.deft-directive-disable"
   if [ -f "$_kill" ] && [ ! -L "$_kill" ]; then
     if ! git -C "$REPO_ROOT" ls-files --error-unmatch -- .deft-directive-disable >/dev/null 2>&1; then
-      echo "Directive is DISABLED for this project via root .deft-directive-disable (test/local kill-switch)." >&2
-      echo "Git hooks skipping Directive CLI spawn (#5543 / #3039). Deposit may remain." >&2
-      echo "Recovery: rm .deft-directive-disable && start a new agent session." >&2
       return 0
     fi
   fi
+  RUNTIME_BIN="$REPO_ROOT/${RUNTIME_BIN_REL}"
+  if [ ! -f "$RUNTIME_BIN" ]; then
+    echo "directive hooks: missing $RUNTIME_BIN" >&2
+    echo "${HOST_HOOK_MISSING_PIN_PROJECT_PM_GUIDANCE}" >&2
+    exit 1
+  fi
   node "$RUNTIME_BIN" "$@"
 }
 `;
@@ -771,7 +851,9 @@ export function ensureGitHooks(projectRoot, options = {}) {
         { rel: ".githooks/pre-push", body: PRE_PUSH },
     ];
     for (const file of files) {
-        const next = file.body.endsWith("\n") ? file.body : `${file.body}\n`;
+        const override = options.testOnlyNextBodyByRel?.[file.rel];
+        const rawNext = override ?? file.body;
+        const next = rawNext.endsWith("\n") ? rawNext : `${rawNext}\n`;
         const prior = readText(join(projectRoot, file.rel));
         if (prior !== null && prior !== next && !isOurGitHookBody(file.rel, prior)) {
             conflicts.push(`${file.rel}: existing hook is not Directive-managed; refusing to overwrite (chain or remove manually)`);