javi-forge 1.31.0 → 1.33.0

package/dist/cli/dispatch/hooks.d.ts

@@ -4,8 +4,11 @@
  * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
  * minimal, because hooks are on the commit/push hot path.
  *
- * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
- * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ * Subcommands:
+ *   - `hooks run <pre-commit|pre-push>` → runHook, exits with its code.
+ *   - `hooks <install|doctor|repair> claude [--force]` → runClaudeHookCommand,
+ *     exits with its code (wrong/missing target → usage + exit 1).
+ * Any other subcommand or a missing name → usage + exit 1.
  */
 import type { CLI } from "./types.js";
 export declare function handleHooks(cli: CLI): Promise<void>;

package/dist/cli/dispatch/hooks.js

@@ -4,8 +4,11 @@
  * (`./commands/hooks.js`) is lazy-imported inside the handler to keep cold-start
  * minimal, because hooks are on the commit/push hot path.
  *
- * Only subcommand: `hooks run <pre-commit|pre-push>` → dispatches to runHook and
- * exits with its code. Any other subcommand or a missing name → usage + exit 1.
+ * Subcommands:
+ *   - `hooks run <pre-commit|pre-push>` → runHook, exits with its code.
+ *   - `hooks <install|doctor|repair> claude [--force]` → runClaudeHookCommand,
+ *     exits with its code (wrong/missing target → usage + exit 1).
+ * Any other subcommand or a missing name → usage + exit 1.
  */
 import { HOOKS_HELP_TEXT } from "../help.js";
 export async function handleHooks(cli) {
@@ -23,6 +26,17 @@ export async function handleHooks(cli) {
         const code = await runHook(name, process.cwd());
         process.exit(code);
     }
+    const sub = cli.input[1];
+    if (sub === "install" || sub === "doctor" || sub === "repair") {
+        if (cli.input[2] !== "claude") {
+            console.error(`Usage: javi-forge hooks ${sub} claude`);
+            process.exit(1);
+        }
+        const { runClaudeHookCommand } = await import("../../commands/claude-hooks.js");
+        process.exit(await runClaudeHookCommand(sub, process.cwd(), {
+            force: cli.flags.force === true,
+        }));
+    }
     // No subcommand → show usage (exit 0). An unknown subcommand is a typo →
     // show usage but exit 1 rather than run nothing silently.
     console.log(HOOKS_HELP_TEXT);

package/dist/cli/help.d.ts

@@ -19,7 +19,7 @@ export declare const CI_HELP_TEXT = "\n  Usage\n    $ javi-forge ci [subcommand]
  * Per-command help for `hooks`, shown by `javi-forge hooks --help` (or when
  * `hooks` is given an unknown subcommand). Whitespace is significant.
  */
-export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit  Run the composed pre-commit sections\n    run pre-push    Run the composed pre-push sections\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n";
+export declare const HOOKS_HELP_TEXT = "\n  Usage\n    $ javi-forge hooks run <pre-commit|pre-push>\n    $ javi-forge hooks <install|doctor|repair> claude [--force]\n\n    Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed\n    cheap\u2192expensive order, fail-fast. With no hooks: config the default is the\n    quick native CI gate (setup + lint + compile + gates \u2014 no tests, no coverage).\n\n  Subcommands\n    run pre-commit    Run the composed pre-commit sections\n    run pre-push      Run the composed pre-push sections\n    install claude    Install the managed Claude PreToolUse guard (.claude/)\n    doctor claude     Report Claude PreToolUse guard health (informational)\n    repair claude     Repair the managed guard; --force overwrites edited assets\n\n  Notes\n    A blocking section failure exits non-zero and blocks the commit/push.\n    A broken .javi-forge/ci.yaml exits 1 (fail-closed \u2014 never skips a gate).\n    To skip: git commit --no-verify   (pre-push: git push --no-verify)\n    doctor claude is informational (always exits 0); install/repair exit 0 on\n    success, non-zero on refusal/failure. Use repair claude --force to overwrite\n    a locally edited managed asset.\n\n  Examples\n    $ javi-forge hooks run pre-commit\n    $ javi-forge hooks run pre-push\n    $ javi-forge hooks install claude\n    $ javi-forge hooks doctor claude\n    $ javi-forge hooks repair claude --force\n";
 export declare const FLAGS_SCHEMA: {
     readonly help: {
         readonly type: "boolean";

package/dist/cli/help.js

@@ -166,23 +166,33 @@ export const CI_HELP_TEXT = `
 export const HOOKS_HELP_TEXT = `
   Usage
     $ javi-forge hooks run <pre-commit|pre-push>
+    $ javi-forge hooks <install|doctor|repair> claude [--force]
 
     Run the sections enabled under hooks: in .javi-forge/ci.yaml, in a fixed
     cheap→expensive order, fail-fast. With no hooks: config the default is the
     quick native CI gate (setup + lint + compile + gates — no tests, no coverage).
 
   Subcommands
-    run pre-commit  Run the composed pre-commit sections
-    run pre-push    Run the composed pre-push sections
+    run pre-commit    Run the composed pre-commit sections
+    run pre-push      Run the composed pre-push sections
+    install claude    Install the managed Claude PreToolUse guard (.claude/)
+    doctor claude     Report Claude PreToolUse guard health (informational)
+    repair claude     Repair the managed guard; --force overwrites edited assets
 
   Notes
     A blocking section failure exits non-zero and blocks the commit/push.
     A broken .javi-forge/ci.yaml exits 1 (fail-closed — never skips a gate).
     To skip: git commit --no-verify   (pre-push: git push --no-verify)
+    doctor claude is informational (always exits 0); install/repair exit 0 on
+    success, non-zero on refusal/failure. Use repair claude --force to overwrite
+    a locally edited managed asset.
 
   Examples
     $ javi-forge hooks run pre-commit
     $ javi-forge hooks run pre-push
+    $ javi-forge hooks install claude
+    $ javi-forge hooks doctor claude
+    $ javi-forge hooks repair claude --force
 `;
 export const FLAGS_SCHEMA = {
     // `--help` is handled manually (autoHelp is disabled at the entrypoint so

package/dist/commands/claude-hooks.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `javi-forge hooks <install|doctor|repair> claude` — console-only renderer for
+ * the already-tested Claude PreToolUse guard library (Slice 4a). It wires the
+ * three lib fns to human output + exit codes; it adds NO new security logic and
+ * never touches `runTransaction`/secure-fs directly.
+ *
+ * Honest-execution gate (Slice 4b): the doctor renderer prints the real
+ * `execution` verdict computed by the library — `runnable`, `blocked`, or
+ * `inconclusive` — plus its `blockers`, `unknownSources`, and the constant
+ * `residual` caveats, in committed stable order. The doctor exit code follows
+ * `execution.status` (runnable → 0, blocked → 1, inconclusive → 2), independent
+ * of `report.healthy`. The renderer never fabricates `runnable`: the library
+ * only reports it when every relevant local source read clear and the guard is
+ * current.
+ */
+import { doctorClaudePreToolUse, installClaudePreToolUse, repairClaudePreToolUse } from "../lib/claude-hook-manager.js";
+export type ClaudeHookSub = "install" | "doctor" | "repair";
+/** Injectable seams for tests; each defaults to the real implementation. */
+export interface ClaudeHookCmdDeps {
+    install?: typeof installClaudePreToolUse;
+    doctor?: typeof doctorClaudePreToolUse;
+    repair?: typeof repairClaudePreToolUse;
+    log?: (msg: string) => void;
+    logError?: (msg: string) => void;
+}
+/**
+ * Run one Claude-hook subcommand against `projectDir`. Returns the process exit
+ * code (the dispatcher calls `process.exit`, not this fn):
+ *   - install/repair: 0 when `ok`, 1 on refusal/failure.
+ *   - doctor: follows `execution.status` — runnable → 0, blocked → 1,
+ *     inconclusive → 2.
+ */
+export declare function runClaudeHookCommand(sub: ClaudeHookSub, projectDir: string, opts: {
+    force?: boolean;
+}, deps?: ClaudeHookCmdDeps): Promise<number>;
+//# sourceMappingURL=claude-hooks.d.ts.map

package/dist/commands/claude-hooks.js

@@ -0,0 +1,98 @@
+/**
+ * `javi-forge hooks <install|doctor|repair> claude` — console-only renderer for
+ * the already-tested Claude PreToolUse guard library (Slice 4a). It wires the
+ * three lib fns to human output + exit codes; it adds NO new security logic and
+ * never touches `runTransaction`/secure-fs directly.
+ *
+ * Honest-execution gate (Slice 4b): the doctor renderer prints the real
+ * `execution` verdict computed by the library — `runnable`, `blocked`, or
+ * `inconclusive` — plus its `blockers`, `unknownSources`, and the constant
+ * `residual` caveats, in committed stable order. The doctor exit code follows
+ * `execution.status` (runnable → 0, blocked → 1, inconclusive → 2), independent
+ * of `report.healthy`. The renderer never fabricates `runnable`: the library
+ * only reports it when every relevant local source read clear and the guard is
+ * current.
+ */
+import { doctorClaudePreToolUse, installClaudePreToolUse, repairClaudePreToolUse, } from "../lib/claude-hook-manager.js";
+function renderMutation(verb, result, log, logError) {
+    if (result.ok) {
+        log(`${verb} claude: ok`);
+        if (result.changed.length > 0) {
+            log("changed:");
+            for (const p of result.changed)
+                log(`  ${p}`);
+        }
+        else {
+            log("changed: nothing (already up to date)");
+        }
+        if (result.backups.length > 0) {
+            log("backups:");
+            for (const p of result.backups)
+                log(`  ${p}`);
+        }
+        return 0;
+    }
+    logError(`${verb} claude: refused`);
+    for (const e of result.errors)
+        logError(`  ${e}`);
+    return 1;
+}
+function renderDoctor(report, log) {
+    log(`doctor claude: ${report.healthy ? "healthy" : "unhealthy"}`);
+    log(`  settings: ${report.settings.state} — ${report.settings.detail}`);
+    log(`  asset:    ${report.asset.state} — ${report.asset.detail}`);
+    log(`  node:     ${report.node.version ?? "unavailable"} (min-satisfied: ${report.node.satisfiesMinimum})`);
+    const execution = report.execution;
+    log(`  execution: ${execution.status}`);
+    if (execution.blockers.length > 0) {
+        log("  blockers:");
+        for (const b of execution.blockers)
+            log(`    - ${b}`);
+    }
+    if (execution.unknownSources.length > 0) {
+        log("  unknown-sources:");
+        for (const u of execution.unknownSources)
+            log(`    - ${u}`);
+    }
+    if (execution.residual.length > 0) {
+        log("  execution-residual:");
+        for (const r of execution.residual)
+            log(`    - ${r}`);
+    }
+    log(`  host-residual: ${report.hostResidual}`);
+    if (report.remediation.length > 0) {
+        log("  remediation:");
+        for (const r of report.remediation)
+            log(`    - ${r}`);
+    }
+    // The doctor exit code follows the effective-execution verdict, independent
+    // of component health: runnable → 0, blocked → 1, inconclusive → 2.
+    if (execution.status === "blocked")
+        return 1;
+    if (execution.status === "inconclusive")
+        return 2;
+    return 0;
+}
+/**
+ * Run one Claude-hook subcommand against `projectDir`. Returns the process exit
+ * code (the dispatcher calls `process.exit`, not this fn):
+ *   - install/repair: 0 when `ok`, 1 on refusal/failure.
+ *   - doctor: follows `execution.status` — runnable → 0, blocked → 1,
+ *     inconclusive → 2.
+ */
+export async function runClaudeHookCommand(sub, projectDir, opts, deps = {}) {
+    const log = deps.log ?? ((m) => console.log(m));
+    const logError = deps.logError ?? ((m) => console.error(m));
+    const install = deps.install ?? installClaudePreToolUse;
+    const doctor = deps.doctor ?? doctorClaudePreToolUse;
+    const repair = deps.repair ?? repairClaudePreToolUse;
+    if (sub === "install") {
+        return renderMutation("install", await install(projectDir), log, logError);
+    }
+    if (sub === "repair") {
+        const result = await repair(projectDir, { force: opts.force === true });
+        return renderMutation("repair", result, log, logError);
+    }
+    return renderDoctor(await doctor(projectDir), log);
+}
+//# sourceMappingURL=claude-hooks.js.map

package/dist/commands/init/steps/security.d.ts

@@ -1,11 +1,15 @@
 import type { StepFn } from "../types.js";
 /**
- * Step 14: Scaffold security hooks (hook-consolidation S4 fold).
+ * Step 14: Scaffold security hooks (hook-consolidation S4 fold + SkillGuard 4a).
  *
  * - When options.securityHooks is false, reports "skipped".
  * - Otherwise:
- *   1. Copies the kiteguard-style runtime settings to `.claude/settings.json`
- *      when absent (KEPT — this is a real feature).
+ *   1. When `claudePreToolUseGuard` is set, installs the managed Claude
+ *      PreToolUse guard via the transactional `installClaudePreToolUse`
+ *      (SkillGuard Slice 4a). The legacy copy-if-absent
+ *      `claude-settings-security.json` scaffold is RETIRED — the managed
+ *      installer owns `.claude/settings.json` + the hook asset with proper
+ *      ownership markers.
  *   2. Merges the `hooks:` security sections for the selected reliability
  *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
  *      minimal `version: 2` config when absent). The dispatcher composes these

package/dist/commands/init/steps/security.js

@@ -1,8 +1,5 @@
-import path from "node:path";
-import fs from "fs-extra";
-import { SECURITY_HOOKS_DIR } from "../../../constants.js";
 import { setHookFeature } from "../../../lib/ci-config.js";
-import { ensureDirExists } from "../../../lib/common.js";
+import { installClaudePreToolUse } from "../../../lib/claude-hook-manager.js";
 import { report } from "../report.js";
 /**
  * Hook-feature preset per reliability profile (hook-consolidation S4).
@@ -21,12 +18,16 @@ const PROFILE_PRESET = {
     strict: { preCommit: ["secrets", "permissions"], prePush: ["deps"] },
 };
 /**
- * Step 14: Scaffold security hooks (hook-consolidation S4 fold).
+ * Step 14: Scaffold security hooks (hook-consolidation S4 fold + SkillGuard 4a).
  *
  * - When options.securityHooks is false, reports "skipped".
  * - Otherwise:
- *   1. Copies the kiteguard-style runtime settings to `.claude/settings.json`
- *      when absent (KEPT — this is a real feature).
+ *   1. When `claudePreToolUseGuard` is set, installs the managed Claude
+ *      PreToolUse guard via the transactional `installClaudePreToolUse`
+ *      (SkillGuard Slice 4a). The legacy copy-if-absent
+ *      `claude-settings-security.json` scaffold is RETIRED — the managed
+ *      installer owns `.claude/settings.json` + the hook asset with proper
+ *      ownership markers.
  *   2. Merges the `hooks:` security sections for the selected reliability
  *      profile into `.javi-forge/ci.yaml` via `setHookFeature` (creating a
  *      minimal `version: 2` config when absent). The dispatcher composes these
@@ -37,7 +38,7 @@ const PROFILE_PRESET = {
  */
 export const stepSecurityHooks = async (ctx) => {
     const { projectDir, dryRun, onStep, options } = ctx;
-    const { securityHooks, hookProfile } = options;
+    const { securityHooks, hookProfile, claudePreToolUseGuard } = options;
     const stepId = "security-hooks";
     report(onStep, stepId, "Scaffold security hooks", "running");
     try {
@@ -48,18 +49,22 @@ export const stepSecurityHooks = async (ctx) => {
         const profile = hookProfile ?? "standard";
         const preset = PROFILE_PRESET[profile];
         if (dryRun) {
-            report(onStep, stepId, "Scaffold security hooks", "done", `dry-run: would merge ${profile} hooks preset + copy .claude/settings.json`);
+            const guardNote = claudePreToolUseGuard
+                ? " + install Claude PreToolUse guard"
+                : "";
+            report(onStep, stepId, "Scaffold security hooks", "done", `dry-run: would merge ${profile} hooks preset${guardNote}`);
             return;
         }
-        // 1. Copy the kiteguard-style runtime security settings to .claude/.
-        const settingsSrc = path.join(SECURITY_HOOKS_DIR, "claude-settings-security.json");
-        if (await fs.pathExists(settingsSrc)) {
-            const claudeDir = path.join(projectDir, ".claude");
-            await ensureDirExists(claudeDir);
-            const settingsDest = path.join(claudeDir, "settings.json");
-            if (!(await fs.pathExists(settingsDest))) {
-                await fs.copy(settingsSrc, settingsDest);
+        // 1. Install the managed Claude PreToolUse guard (transactional; owns
+        //    .claude/settings.json + the hook asset). Retires the legacy copy.
+        let guardNote = "";
+        if (claudePreToolUseGuard) {
+            const result = await installClaudePreToolUse(projectDir);
+            if (!result.ok) {
+                report(onStep, stepId, "Scaffold security hooks", "error", `Claude guard install refused: ${result.errors.join("; ")}`);
+                return;
             }
+            guardNote = "; Claude guard installed";
         }
         // 2. Merge the profile's security sections into .javi-forge/ci.yaml.
         for (const feature of preset.preCommit) {
@@ -72,9 +77,10 @@ export const stepSecurityHooks = async (ctx) => {
             ...preset.preCommit.map((f) => `pre-commit.${f}`),
             ...preset.prePush.map((f) => `pre-push.${f}`),
         ];
-        report(onStep, stepId, "Scaffold security hooks", "done", merged.length > 0
+        const presetNote = merged.length > 0
             ? `${profile} preset: ${merged.join(", ")}`
-            : `${profile} preset: CI gate only (no security sections)`);
+            : `${profile} preset: CI gate only (no security sections)`;
+        report(onStep, stepId, "Scaffold security hooks", "done", `${presetNote}${guardNote}`);
     }
     catch (e) {
         report(onStep, stepId, "Scaffold security hooks", "error", String(e));

package/dist/lib/claude-hook-manager.d.ts

@@ -51,6 +51,7 @@ export interface ClaudeHookDoctorReport {
     coverage: typeof COVERAGE;
     hostResidual: string;
     remediation: readonly string[];
+    execution: ExecutionReport;
 }
 /**
  * Classify the asset into one of nine states from observed bytes only. Never
@@ -66,14 +67,100 @@ export declare function detectNode(nodeVersion: string | undefined): {
     version?: string;
     satisfiesMinimum: boolean;
 };
+/**
+ * The honest effective-execution verdict. `status` is derived by precedence
+ * (blocked > inconclusive > runnable); `runnable` is reached only when every
+ * relevant local source read clear AND the managed guard is current. `residual`
+ * carries CONSTANT honest caveats (server-delivered policy, session safe-mode)
+ * that are always shown but never gate the status — otherwise `runnable` would
+ * be unreachable.
+ */
+export interface ExecutionReport {
+    status: "runnable" | "blocked" | "inconclusive";
+    blockers: string[];
+    unknownSources: string[];
+    residual: string[];
+}
+/** Injectable seams so units never hard-read real `/etc` or `/Library`. */
+export interface ExecutionProbeEnv {
+    platform?: NodeJS.Platform;
+    homeDir?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Override the managed OS file (null → no managed file at all). */
+    managedFile?: string | null;
+    /** Override the managed drop-in dir (null → no drop-ins). */
+    managedDropInDir?: string | null;
+    /** Override the drop-in directory listing (defaults to a confined readdir). */
+    listDir?: (dir: string) => Promise<string[]>;
+}
+/** Per-source read outcome; never promotes an unobservable source to clear. */
+export type ExecutionSourceProbe = {
+    kind: "clear";
+} | {
+    kind: "blocking";
+    flag: "disableAllHooks" | "allowManagedHooksOnly";
+} | {
+    kind: "unknown";
+    reason: string;
+};
+/** The already-computed component states the guard-currency check consumes. */
+export interface ExecutionComponentStates {
+    asset: ClaudeHookComponentState;
+    settings: ClaudeHookComponentState;
+}
+export interface ManagedSettingsPaths {
+    file: string;
+    dropInDir: string;
+}
+/** Static managed-settings locations per OS (no fs). WSL reports `linux`. */
+export declare function resolveManagedSettingsPaths(platform: NodeJS.Platform): ManagedSettingsPaths;
+/**
+ * Probe one settings source path for the two documented hook-neutralizing
+ * flags. Fail-closed: only a genuinely-absent path or a cleanly-parsed source
+ * with no flag is `clear`; a symlink, non-regular path, permission/io error,
+ * oversized/binary content, or malformed JSON is `unknown` (unreadable ≠
+ * absent), never `clear`. `disableAllHooks` is preferred over
+ * `allowManagedHooksOnly` when both are set (the former blocks at any source).
+ */
+export declare function probeExecutionSource(target: string): Promise<ExecutionSourceProbe>;
+/**
+ * Confined readdir result of the managed drop-in dir, fail-closed and mirroring
+ * `probeExecutionSource`'s errno classification: a genuinely-absent directory
+ * (ENOENT/ENOTDIR) is the ONLY empty/clear case, so it yields `{ entries: [] }`
+ * (no drop-ins). ANY other readdir failure (EACCES/EIO/ELOOP/…) means the
+ * directory is present-but-unenumerable and MUST NOT be treated as empty — it
+ * yields `{ unreadable: true }` so the caller can degrade the verdict, never
+ * silently report "no drop-ins" (a false `runnable`).
+ */
+export type ManagedDropInListing = {
+    unreadable?: false;
+    entries: string[];
+} | {
+    unreadable: true;
+    reason: string;
+};
+export declare function listManagedDropIns(dir: string, listDir?: (dir: string) => Promise<string[]>): Promise<ManagedDropInListing>;
+/**
+ * The fail-closed effective-execution verdict. Gathers all sources in stable
+ * order (project, local, user, managed OS file, drop-ins sorted), classifies
+ * each with `probeExecutionSource`, applies the managed-only inertness of
+ * `allowManagedHooksOnly` (blocks only from a managed source — hooks MERGE
+ * elsewhere), folds in the guard-currency blocker and the doctor-process
+ * safe-mode observation, then resolves by precedence
+ * (`blockers` first, then `unknownSources`, else `runnable`). An `unknown` is
+ * NEVER promoted to `runnable`.
+ */
+export declare function probeExecution(projectDir: string, componentStates: ExecutionComponentStates, env?: ExecutionProbeEnv): Promise<ExecutionReport>;
 /**
  * Assemble the read-only component-level doctor report (no writes). `healthy` is
  * exactly: both components `managed-current`, matcher and command shape exact,
  * Node `>=22`. `assetSettingsConsistent` is a reported advisory, NOT part of it.
+ * The `execution` verdict is INDEPENDENT of `healthy`.
  */
 export declare function doctorClaudePreToolUse(projectDir: string, options?: {
     manifest?: Manifest;
     nodeVersion?: string;
+    execution?: ExecutionProbeEnv;
 }): Promise<ClaudeHookDoctorReport>;
 export interface ClaudeHookMutationResult {
     ok: boolean;

package/dist/lib/claude-hook-manager.js

@@ -8,11 +8,12 @@
  * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
  */
 import { createHash, randomBytes } from "node:crypto";
-import { lstat, readFile } from "node:fs/promises";
+import { lstat, readdir, readFile } from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import { CLAUDE_HOOK_ASSETS_DIR } from "../constants.js";
 import { ASSET_MANAGED_MARKER, ASSET_NAME, } from "./__fixtures__/claude-hook-ownership.js";
-import { buildManagedContainer, classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, planForceReplace, planLegacyCohortExcision, planManagedClaudeHookMerge, } from "./claude-hook-settings.js";
+import { buildManagedContainer, classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, planForceReplace, planLegacyCohortExcision, planManagedClaudeHookMerge, scanExecutionFlags, } from "./claude-hook-settings.js";
 import { safeReadFile } from "./safe-read.js";
 import { selectSecureFs } from "./secure-fs-posix.js";
 import { runTransaction, } from "./secure-fs-transaction.js";
@@ -200,10 +201,201 @@ const REMEDIATION = {
 function remediationFor(state, component) {
     return REMEDIATION[state]?.replace("$", component);
 }
+/** Static managed-settings locations per OS (no fs). WSL reports `linux`. */
+export function resolveManagedSettingsPaths(platform) {
+    if (platform === "darwin") {
+        const base = "/Library/Application Support/ClaudeCode";
+        return {
+            file: `${base}/managed-settings.json`,
+            dropInDir: `${base}/managed-settings.d`,
+        };
+    }
+    if (platform === "win32") {
+        const base = "C:\\Program Files\\ClaudeCode";
+        return {
+            file: `${base}\\managed-settings.json`,
+            dropInDir: `${base}\\managed-settings.d`,
+        };
+    }
+    const base = "/etc/claude-code";
+    return {
+        file: `${base}/managed-settings.json`,
+        dropInDir: `${base}/managed-settings.d`,
+    };
+}
+/**
+ * Probe one settings source path for the two documented hook-neutralizing
+ * flags. Fail-closed: only a genuinely-absent path or a cleanly-parsed source
+ * with no flag is `clear`; a symlink, non-regular path, permission/io error,
+ * oversized/binary content, or malformed JSON is `unknown` (unreadable ≠
+ * absent), never `clear`. `disableAllHooks` is preferred over
+ * `allowManagedHooksOnly` when both are set (the former blocks at any source).
+ */
+export async function probeExecutionSource(target) {
+    const stat = await lstatNoFollow(target);
+    if (stat.kind === "enoent")
+        return { kind: "clear" };
+    if (stat.kind === "symlink")
+        return { kind: "unknown", reason: "symlink" };
+    if (stat.kind === "non-regular") {
+        return { kind: "unknown", reason: "non-regular" };
+    }
+    if (stat.kind === "error")
+        return { kind: "unknown", reason: stat.detail };
+    const read = await safeReadFile(target, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return { kind: "clear" };
+        return { kind: "unknown", reason: read.reason };
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(read.content);
+    }
+    catch {
+        return { kind: "unknown", reason: "invalid-json" };
+    }
+    const flags = scanExecutionFlags(parsed);
+    if (flags.disableAllHooks) {
+        return { kind: "blocking", flag: "disableAllHooks" };
+    }
+    if (flags.allowManagedHooksOnly) {
+        return { kind: "blocking", flag: "allowManagedHooksOnly" };
+    }
+    return { kind: "clear" };
+}
+export async function listManagedDropIns(dir, listDir) {
+    let entries;
+    try {
+        entries = listDir ? await listDir(dir) : await readdir(dir);
+    }
+    catch (error) {
+        const code = error.code;
+        // Only a genuinely-absent directory is "no drop-ins"; every other error
+        // (permission/io/loop/etc.) is an unreadable managed source.
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { entries: [] };
+        return { unreadable: true, reason: code ?? String(error) };
+    }
+    return {
+        entries: entries
+            .filter((name) => name.endsWith(".json"))
+            .sort()
+            .map((name) => path.join(dir, name)),
+    };
+}
+/** CONSTANT honest limits — always rendered, never gate the status. */
+const EXECUTION_RESIDUAL = [
+    "server-delivered managed policy can disable hooks and is not observable from local files",
+    "session safe-mode (--safe-mode / CLAUDE_CODE_SAFE_MODE) in the diagnosed session is not observable from this process",
+];
+function isSafeModeTruthy(env) {
+    const value = env.CLAUDE_CODE_SAFE_MODE;
+    if (value === undefined)
+        return false;
+    const normalized = value.trim().toLowerCase();
+    return normalized !== "" && normalized !== "0" && normalized !== "false";
+}
+/**
+ * The fail-closed effective-execution verdict. Gathers all sources in stable
+ * order (project, local, user, managed OS file, drop-ins sorted), classifies
+ * each with `probeExecutionSource`, applies the managed-only inertness of
+ * `allowManagedHooksOnly` (blocks only from a managed source — hooks MERGE
+ * elsewhere), folds in the guard-currency blocker and the doctor-process
+ * safe-mode observation, then resolves by precedence
+ * (`blockers` first, then `unknownSources`, else `runnable`). An `unknown` is
+ * NEVER promoted to `runnable`.
+ */
+export async function probeExecution(projectDir, componentStates, env = {}) {
+    const platform = env.platform ?? process.platform;
+    const homeDir = env.homeDir ?? os.homedir();
+    const processEnv = env.env ?? process.env;
+    const resolved = resolveManagedSettingsPaths(platform);
+    const managedFile = env.managedFile !== undefined ? env.managedFile : resolved.file;
+    const dropInDir = env.managedDropInDir !== undefined
+        ? env.managedDropInDir
+        : resolved.dropInDir;
+    const specs = [
+        {
+            label: "project",
+            target: path.join(projectDir, ".claude", "settings.json"),
+            managed: false,
+        },
+        {
+            label: "local",
+            target: path.join(projectDir, ".claude", "settings.local.json"),
+            managed: false,
+        },
+        {
+            label: "user",
+            target: path.join(homeDir, ".claude", "settings.json"),
+            managed: false,
+        },
+    ];
+    if (managedFile) {
+        specs.push({ label: "managed", target: managedFile, managed: true });
+    }
+    // A present-but-unenumerable drop-in dir is an `unknown` managed source, NOT
+    // "no drop-ins" — fold it into unknownSources so a blocking drop-in policy we
+    // cannot read can never be mistaken for a clear (false `runnable`) verdict.
+    let dropInDirUnknown;
+    if (dropInDir) {
+        const listing = await listManagedDropIns(dropInDir, env.listDir);
+        if (listing.unreadable) {
+            dropInDirUnknown = `managed:${dropInDir} (${listing.reason})`;
+        }
+        else {
+            for (const target of listing.entries) {
+                specs.push({ label: "managed", target, managed: true });
+            }
+        }
+    }
+    const blockers = [];
+    const unknownSources = [];
+    for (const spec of specs) {
+        const probe = await probeExecutionSource(spec.target);
+        if (probe.kind === "clear")
+            continue;
+        if (probe.kind === "unknown") {
+            unknownSources.push(`${spec.label}:${spec.target} (${probe.reason})`);
+            continue;
+        }
+        // `allowManagedHooksOnly` is inert outside a managed source (hooks merge).
+        if (probe.flag === "allowManagedHooksOnly" && !spec.managed)
+            continue;
+        blockers.push(`policy:${probe.flag}@${spec.label}`);
+    }
+    if (dropInDirUnknown)
+        unknownSources.push(dropInDirUnknown);
+    // Guard-currency: a not-installed / drifted guard cannot fire, so it blocks.
+    if (componentStates.asset !== "managed-current") {
+        blockers.push(`guard:asset=${componentStates.asset}`);
+    }
+    if (componentStates.settings !== "managed-current") {
+        blockers.push(`guard:settings=${componentStates.settings}`);
+    }
+    // Safe-mode observed in THIS doctor process is a real per-run unknown (the
+    // diagnosed session's own safe-mode remains a constant residual).
+    if (isSafeModeTruthy(processEnv)) {
+        unknownSources.push("safe-mode:CLAUDE_CODE_SAFE_MODE (observed in doctor process only)");
+    }
+    const status = blockers.length > 0
+        ? "blocked"
+        : unknownSources.length > 0
+            ? "inconclusive"
+            : "runnable";
+    return {
+        status,
+        blockers,
+        unknownSources,
+        residual: [...EXECUTION_RESIDUAL],
+    };
+}
 /**
  * Assemble the read-only component-level doctor report (no writes). `healthy` is
  * exactly: both components `managed-current`, matcher and command shape exact,
  * Node `>=22`. `assetSettingsConsistent` is a reported advisory, NOT part of it.
+ * The `execution` verdict is INDEPENDENT of `healthy`.
  */
 export async function doctorClaudePreToolUse(projectDir, options) {
     const manifest = options?.manifest ?? (await readManifest());
@@ -240,6 +432,7 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         signals.matcherExact &&
         signals.commandShapeExact &&
         node.satisfiesMinimum;
+    const execution = await probeExecution(projectDir, { asset: asset.state, settings: settings.state }, options?.execution ?? {});
     return {
         healthy,
         settings: {
@@ -261,6 +454,7 @@ export async function doctorClaudePreToolUse(projectDir, options) {
         coverage: COVERAGE,
         hostResidual: HOST_RESIDUAL,
         remediation: [...remediation].sort(),
+        execution,
     };
 }
 async function readManifest() {

package/dist/lib/claude-hook-settings.d.ts

@@ -40,6 +40,24 @@ export declare function isPlainObject(value: unknown): value is Record<string, u
  * else is malformed.
  */
 export declare function validateSettingsShape(parsed: unknown): boolean;
+/**
+ * The two documented scalar flags a settings source can set that neutralize the
+ * managed hook. `disableAllHooks: true` at ANY source is a blocker; the
+ * source→blocker mapping for `allowManagedHooksOnly` (managed-only) lives in the
+ * manager, which knows each source's provenance.
+ */
+export interface ExecutionFlagScan {
+    disableAllHooks: boolean;
+    allowManagedHooksOnly: boolean;
+}
+/**
+ * Classify an already-parsed settings container for the two documented
+ * hook-neutralizing flags. Strict `=== true` only: a truthy-but-not-`true`
+ * value (`"true"`, `1`), a missing key, or a non-object input is NOT a flag.
+ * A false here is a definitive "this source does not set the flag", never an
+ * "unknown" — unreadability is decided upstream by the fs probe, not here.
+ */
+export declare function scanExecutionFlags(parsed: unknown): ExecutionFlagScan;
 /**
  * Replace the trailing 64-hex asset SHA token in a managed `statusMessage` with
  * the fixed placeholder so settings identity is invariant under asset rotation.

package/dist/lib/claude-hook-settings.js

@@ -31,6 +31,22 @@ export function validateSettingsShape(parsed) {
         return false;
     return true;
 }
+/**
+ * Classify an already-parsed settings container for the two documented
+ * hook-neutralizing flags. Strict `=== true` only: a truthy-but-not-`true`
+ * value (`"true"`, `1`), a missing key, or a non-object input is NOT a flag.
+ * A false here is a definitive "this source does not set the flag", never an
+ * "unknown" — unreadability is decided upstream by the fs probe, not here.
+ */
+export function scanExecutionFlags(parsed) {
+    if (!isPlainObject(parsed)) {
+        return { disableAllHooks: false, allowManagedHooksOnly: false };
+    }
+    return {
+        disableAllHooks: parsed.disableAllHooks === true,
+        allowManagedHooksOnly: parsed.allowManagedHooksOnly === true,
+    };
+}
 // Canonical identity (Decision ②)
 const ASSET_SHA_TOKEN = /^[0-9a-f]{64}$/;
 const VERSION_PATTERN = /^javi-forge-global-pretooluse:v(\d+):sha256:/;

package/dist/types/index.d.ts

@@ -16,6 +16,11 @@ export interface InitOptions {
     claudeMd: boolean;
     securityHooks: boolean;
     hookProfile: HookProfile;
+    /**
+     * Install the managed Claude PreToolUse guard during init. Derived from
+     * `securityHooks` at the single App.tsx call site (all profiles incl. Minimal).
+     */
+    claudePreToolUseGuard: boolean;
     codeGraph: boolean;
     dockerDeploy: boolean;
     /** Service name for docker rollout (default: 'app') */

package/dist/ui/App.js

@@ -93,6 +93,9 @@ export default function App({ dryRun = false, presetStack, presetCI, presetMemor
             claudeMd: opts.claudeMd,
             securityHooks: opts.securityHooks,
             hookProfile: opts.hookProfile,
+            // Derived from securityHooks alone — ALL profiles incl. Minimal
+            // install the managed guard when security hooks are enabled.
+            claudePreToolUseGuard: opts.securityHooks,
             codeGraph: opts.codeGraph,
             localAi: opts.localAi,
             dockerDeploy: false,

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "javi-forge",
-	"version": "1.31.0",
+	"version": "1.33.0",
 	"description": "Project scaffolding and AI-ready CI bootstrap",
 	"type": "module",
 	"bin": {