javi-forge 1.28.0 → 1.29.0

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

@@ -0,0 +1,276 @@
+/**
+ * Read-only Claude PreToolUse ownership manager (Slice 2). Its only filesystem
+ * surface is `safeReadFile` plus one isolated no-follow `lstat` helper — it never
+ * writes, creates directories, or makes backups. It owns asset byte
+ * classification (always recompute the full-file SHA), the settings read+parse
+ * wrapper (identity delegated to `claude-hook-settings`), the Node `>=22` check,
+ * and the component-level doctor. Install/repair are declared but unimplemented
+ * Slice-3 seams — Slice 3 GROWS this file, it does not relocate this code.
+ */
+import { createHash } from "node:crypto";
+import { lstat } from "node:fs/promises";
+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 { classifySettingsEntry, isPlainObject, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, } from "./claude-hook-settings.js";
+import { safeReadFile } from "./safe-read.js";
+/** 1 MiB read budget, shared with the runtime's stdin envelope. */
+const ASSET_MAX_BYTES = 1024 * 1024;
+const NODE_MINIMUM_MAJOR = 22;
+const READ_OPTS = {
+    maxBytes: ASSET_MAX_BYTES,
+    hardRejectOverBytes: ASSET_MAX_BYTES,
+    maxLineLength: Number.POSITIVE_INFINITY,
+};
+const COVERAGE = ["Bash", "PowerShell", "Read", "Write", "Edit"];
+const HOST_RESIDUAL = "spawn/start/timeout failures continue through Claude permission flow";
+const ASSET_SHA_TOKEN = /^[0-9a-f]{64}$/;
+async function lstatNoFollow(target) {
+    try {
+        const stats = await lstat(target);
+        if (stats.isSymbolicLink())
+            return { kind: "symlink" };
+        if (!stats.isFile())
+            return { kind: "non-regular" };
+        return { kind: "file" };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === "ENOENT" || code === "ENOTDIR")
+            return { kind: "enoent" };
+        return { kind: "error", detail: code ?? String(error) };
+    }
+}
+/** Hash the observed bytes as UTF-8, matching the manifest's raw-file hash for the managed asset. */
+function sha256Of(content) {
+    return createHash("sha256")
+        .update(Buffer.from(content, "utf8"))
+        .digest("hex");
+}
+/**
+ * Classify the asset into one of nine states from observed bytes only. Never
+ * trusts a claimed hash: the full-file SHA is always recomputed and compared to
+ * the manifest.
+ */
+export async function classifyAssetState(assetPath, manifest) {
+    const stat = await lstatNoFollow(assetPath);
+    if (stat.kind === "enoent")
+        return { state: "absent" };
+    if (stat.kind === "symlink")
+        return { state: "symlink" };
+    if (stat.kind === "non-regular")
+        return { state: "non-regular" };
+    if (stat.kind === "error")
+        return { state: "non-regular", detail: stat.detail };
+    const read = await safeReadFile(assetPath, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return { state: "absent" };
+        if (read.reason === "binary")
+            return { state: "foreign", detail: "binary" };
+        if (read.reason === "too-large") {
+            return { state: "foreign", detail: "exceeds asset budget" };
+        }
+        return { state: "non-regular", detail: read.reason };
+    }
+    if (!read.content.startsWith(`${ASSET_MANAGED_MARKER}\n`)) {
+        return { state: "foreign" };
+    }
+    const sha256 = sha256Of(read.content);
+    if (sha256 === manifest.asset.sha256) {
+        return {
+            state: "managed-current",
+            version: manifest.asset.version,
+            sha256,
+        };
+    }
+    if (manifest.asset.historical.includes(sha256)) {
+        return {
+            state: "released-outdated",
+            version: manifest.asset.version,
+            sha256,
+        };
+    }
+    return { state: "edited-managed", sha256 };
+}
+/** Read `.claude/settings.json` and classify it (lstat → bounded read → legacy SHA → pure classifier). */
+export async function classifySettingsFile(settingsPath, currentAssetSha, identities) {
+    const parsed = await readSettings(settingsPath);
+    if ("state" in parsed)
+        return parsed.classification;
+    return classifySettingsEntry(parsed.value, currentAssetSha, identities);
+}
+const done = (classification) => ({
+    state: true,
+    classification,
+});
+async function readSettings(settingsPath) {
+    const stat = await lstatNoFollow(settingsPath);
+    if (stat.kind === "enoent")
+        return done({ state: "absent" });
+    if (stat.kind === "symlink")
+        return done({ state: "symlink" });
+    if (stat.kind === "non-regular")
+        return done({ state: "non-regular" });
+    if (stat.kind === "error") {
+        return done({ state: "non-regular", detail: stat.detail });
+    }
+    const read = await safeReadFile(settingsPath, READ_OPTS);
+    if (!read.ok) {
+        if (read.reason === "not-found")
+            return done({ state: "absent" });
+        if (read.reason === "binary" || read.reason === "too-large") {
+            return done({ state: "malformed", detail: read.reason });
+        }
+        return done({ state: "non-regular", detail: read.reason });
+    }
+    if (sha256Of(read.content) === LEGACY_FILE_SHA256) {
+        return done({ state: "exact-legacy", detail: "whole-file" });
+    }
+    try {
+        return { value: JSON.parse(read.content) };
+    }
+    catch {
+        return done({ state: "malformed", detail: "invalid-json" });
+    }
+}
+/** Node availability + `>=22` check from a version string (no spawn). */
+export function detectNode(nodeVersion) {
+    if (!nodeVersion)
+        return { available: false, satisfiesMinimum: false };
+    const major = Number.parseInt(nodeVersion.split(".")[0] ?? "", 10);
+    return {
+        available: true,
+        version: nodeVersion,
+        satisfiesMinimum: Number.isFinite(major) && major >= NODE_MINIMUM_MAJOR,
+    };
+}
+const NO_SIGNALS = {
+    matcherExact: false,
+    commandShapeExact: false,
+    assetSettingsConsistent: false,
+};
+/** Derive matcher/command/consistency signals from the marked handler, if any. */
+function settingsSignals(value, classification, currentAssetSha) {
+    if (classification.groupIndex === undefined || !isPlainObject(value)) {
+        return NO_SIGNALS;
+    }
+    const hooks = value.hooks;
+    const groups = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const group = groups[classification.groupIndex];
+    if (!isPlainObject(group) || !Array.isArray(group.hooks))
+        return NO_SIGNALS;
+    const handler = group.hooks[classification.handlerIndex ?? -1];
+    if (!isPlainObject(handler))
+        return NO_SIGNALS;
+    const args = handler.args;
+    const commandShapeExact = handler.type === "command" &&
+        handler.command === "node" &&
+        Array.isArray(args) &&
+        args.length === 1 &&
+        args[0] === MANAGED_ASSET_ARG &&
+        handler.timeout === 30;
+    let assetSettingsConsistent = false;
+    if (typeof handler.statusMessage === "string" &&
+        handler.statusMessage.startsWith(MANAGED_STATUS_PREFIX)) {
+        const token = handler.statusMessage.slice(MANAGED_STATUS_PREFIX.length);
+        assetSettingsConsistent =
+            ASSET_SHA_TOKEN.test(token) && token === currentAssetSha;
+    }
+    return {
+        matcherExact: group.matcher === MANAGED_MATCHER,
+        commandShapeExact,
+        assetSettingsConsistent,
+    };
+}
+const REMEDIATION = {
+    absent: "install the managed $ (Slice 3)",
+    "released-outdated": "upgrade the managed $ (Slice 3)",
+    "exact-legacy": "migrate the legacy $ (Slice 3)",
+    "edited-managed": "repair the managed $ with --force (Slice 3)",
+    foreign: "manually review the $",
+    symlink: "manually review the $",
+    "non-regular": "manually review the $",
+    malformed: "manually review the $",
+};
+function remediationFor(state, component) {
+    return REMEDIATION[state]?.replace("$", component);
+}
+/**
+ * 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.
+ */
+export async function doctorClaudePreToolUse(projectDir, options) {
+    const manifest = options?.manifest ?? (await readManifest());
+    const currentAssetSha = manifest.asset.sha256;
+    const asset = await classifyAssetState(path.join(projectDir, ".claude", "hooks", ASSET_NAME), manifest);
+    const settingsRead = await readSettings(path.join(projectDir, ".claude", "settings.json"));
+    const settings = "state" in settingsRead
+        ? settingsRead.classification
+        : classifySettingsEntry(settingsRead.value, currentAssetSha, manifest.settingsEntries);
+    const signals = "value" in settingsRead
+        ? settingsSignals(settingsRead.value, settings, currentAssetSha)
+        : NO_SIGNALS;
+    const node = detectNode(options?.nodeVersion ?? process.versions.node);
+    const remediation = new Set();
+    if (asset.state !== "managed-current") {
+        const line = remediationFor(asset.state, "asset");
+        if (line)
+            remediation.add(line);
+    }
+    if (settings.state !== "managed-current") {
+        const line = remediationFor(settings.state, "settings");
+        if (line)
+            remediation.add(line);
+    }
+    if (!node.satisfiesMinimum)
+        remediation.add("install Node 22 or newer");
+    if (!signals.matcherExact)
+        remediation.add("restore the exact managed matcher");
+    if (!signals.commandShapeExact) {
+        remediation.add("restore the exact managed command shape");
+    }
+    const healthy = settings.state === "managed-current" &&
+        asset.state === "managed-current" &&
+        signals.matcherExact &&
+        signals.commandShapeExact &&
+        node.satisfiesMinimum;
+    return {
+        healthy,
+        settings: {
+            state: settings.state,
+            version: settings.version,
+            canonicalSha256: settings.canonicalSha256,
+            detail: settings.detail ?? settings.state,
+        },
+        asset: {
+            state: asset.state,
+            version: asset.version,
+            sha256: asset.sha256,
+            detail: asset.detail ?? asset.state,
+        },
+        node,
+        matcherExact: signals.matcherExact,
+        commandShapeExact: signals.commandShapeExact,
+        assetSettingsConsistent: signals.assetSettingsConsistent,
+        coverage: COVERAGE,
+        hostResidual: HOST_RESIDUAL,
+        remediation: [...remediation].sort(),
+    };
+}
+async function readManifest() {
+    const read = await safeReadFile(path.join(CLAUDE_HOOK_ASSETS_DIR, "manifest.json"), READ_OPTS);
+    if (!read.ok)
+        throw new Error(`unreadable claude-hooks manifest: ${read.reason}`);
+    return JSON.parse(read.content);
+}
+export function installClaudePreToolUse(_projectDir) {
+    throw new Error("unimplemented: Slice 3 transaction");
+}
+export function repairClaudePreToolUse(_projectDir, _options) {
+    throw new Error("unimplemented: Slice 3 transaction");
+}
+//# sourceMappingURL=claude-hook-manager.js.map

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

@@ -0,0 +1,116 @@
+/**
+ * Pure settings-entry ownership recognition for the SkillGuard Claude
+ * PreToolUse guard (Slice 2). Every function takes already-parsed JS values and
+ * returns values — ZERO filesystem access (all bytes-on-disk access lives in
+ * `claude-hook-manager.ts`). It covers protocol-shape validation, deterministic
+ * canonical identity (Decision ②: the live asset SHA token is normalized out
+ * before hashing), exact v0 legacy recognition by deep structural equality, and
+ * removal/merge PLANNING only. Identity is always recomputed from observed
+ * structure; a marker only claims ownership, it never proves it.
+ */
+import { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX } from "./__fixtures__/claude-hook-ownership.js";
+export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
+/** The nine independent component states (identical for asset and settings). */
+export type ClaudeHookComponentState = "absent" | "managed-current" | "released-outdated" | "exact-legacy" | "edited-managed" | "foreign" | "symlink" | "non-regular" | "malformed";
+/** A released settings-entry identity: version plus placeholder-normalized hash. */
+export interface CanonicalSettingsEntry {
+    version: number;
+    canonicalSha256: string;
+}
+/** The manifest's settings-entry identity binding. */
+export interface SettingsIdentityManifest {
+    current: CanonicalSettingsEntry | null;
+    historical: CanonicalSettingsEntry[];
+}
+/** Result of classifying a settings container against the manifest identity. */
+export interface SettingsClassification {
+    state: ClaudeHookComponentState;
+    version?: number;
+    canonicalSha256?: string;
+    detail?: string;
+    /** Index of the marked group inside `hooks.PreToolUse`. */
+    groupIndex?: number;
+    /** Index of the marked handler inside the group's `hooks`. */
+    handlerIndex?: number;
+}
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/**
+ * A valid settings container is an object; when `hooks` is present it MUST be
+ * an object; when `hooks.PreToolUse` is present it MUST be an array. Anything
+ * else is malformed.
+ */
+export declare function validateSettingsShape(parsed: unknown): boolean;
+/**
+ * Replace the trailing 64-hex asset SHA token in a managed `statusMessage` with
+ * the fixed placeholder so settings identity is invariant under asset rotation.
+ * A non-managed or malformed token is returned unchanged so it hashes to a
+ * distinct (non-current) value.
+ */
+export declare function normalizeStatusMessage(statusMessage: unknown): string;
+/** Parse the marker version (`…:v1:…` → 1) for diagnostics only. */
+export declare function parseVersionFromStatus(statusMessage: unknown): number | undefined;
+/**
+ * Canonicalize the marker-proven handler group into deterministic bytes and its
+ * SHA-256. Fixed key order (`type,command,args,timeout,statusMessage` inside a
+ * `matcher,hooks` group), the asset-SHA token normalized out, two-space indent
+ * plus a trailing newline. Only the single handler participates.
+ */
+export declare function canonicalizeSettingsEntry(group: unknown, handler: unknown): {
+    serialization: string;
+    canonicalSha256: string;
+};
+/**
+ * Order-sensitive for arrays, key-set-exact (order-insensitive) for objects,
+ * strict for scalars. No substring, normalization, or tolerance.
+ */
+export declare function deepStructuralEqual(a: unknown, b: unknown): boolean;
+/**
+ * In-object legacy recognition: exactly one deep-equal match for each of the
+ * four cohort objects (L1–L3 Pre, L4 Post) is `exact-legacy`; a partial,
+ * duplicate, or edited cohort is `foreign` (partial-legacy); unrecognized
+ * PreToolUse handler content is `foreign` per spec R2; only a container with no
+ * PreToolUse handler content is `absent` (installable). Whole-file SHA legacy is
+ * decided by the manager, which holds the raw bytes. (Spec R2 overrides
+ * design.md Algorithm C, which returns `absent` for the no-cohort fallthrough
+ * and so cannot flag a resembling unmarked handler.)
+ */
+export declare function classifyLegacy(parsed: unknown): SettingsClassification;
+/**
+ * Reduce a parsed settings container to one component state, from parsed
+ * structure only. Shape validation first, then marker-driven identity (always
+ * recomputed), then the legacy fallback when no marker is present.
+ */
+export declare function classifySettingsEntry(parsed: unknown, _currentAssetSha: string, identities: SettingsIdentityManifest): SettingsClassification;
+export interface ManagedRemovalPlan {
+    refused: boolean;
+    reason?: string;
+    state: ClaudeHookComponentState;
+    groupIndex?: number;
+    handlerIndex?: number;
+    /** True when removing the managed handler empties the group. */
+    removeGroup?: boolean;
+    /** Sibling handlers in the group that removal must preserve. */
+    preservedSiblings?: number;
+}
+/**
+ * Plan removal of the marker-proven managed handler. Only a recognized managed
+ * identity (`managed-current` or `released-outdated`) is eligible; foreign,
+ * partial-legacy, edited-managed, and every non-regular state refuse.
+ */
+export declare function planManagedClaudeHookRemoval(parsed: unknown, currentAssetSha: string, identities: SettingsIdentityManifest): ManagedRemovalPlan;
+export interface ManagedMergePlan {
+    refused: boolean;
+    reason?: string;
+    state: ClaudeHookComponentState;
+    action: "install" | "replace" | "noop" | "refuse";
+    groupIndex?: number;
+    handlerIndex?: number;
+    preservedSiblings?: number;
+}
+/**
+ * Plan the managed merge. `absent` installs a new group, `managed-current` is a
+ * no-op, `released-outdated` replaces the marked handler in place (siblings
+ * preserved), and every other state refuses (edited/force is a Slice-3 concern).
+ */
+export declare function planManagedClaudeHookMerge(parsed: unknown, currentAssetSha: string, identities: SettingsIdentityManifest): ManagedMergePlan;
+//# sourceMappingURL=claude-hook-settings.d.ts.map

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

@@ -0,0 +1,283 @@
+/**
+ * Pure settings-entry ownership recognition for the SkillGuard Claude
+ * PreToolUse guard (Slice 2). Every function takes already-parsed JS values and
+ * returns values — ZERO filesystem access (all bytes-on-disk access lives in
+ * `claude-hook-manager.ts`). It covers protocol-shape validation, deterministic
+ * canonical identity (Decision ②: the live asset SHA token is normalized out
+ * before hashing), exact v0 legacy recognition by deep structural equality, and
+ * removal/merge PLANNING only. Identity is always recomputed from observed
+ * structure; a marker only claims ownership, it never proves it.
+ */
+import { createHash } from "node:crypto";
+import { ASSET_SHA_PLACEHOLDER, LEGACY_COHORT, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, } from "./__fixtures__/claude-hook-ownership.js";
+export { ASSET_SHA_PLACEHOLDER, LEGACY_FILE_SHA256, MANAGED_ASSET_ARG, MANAGED_MATCHER, MANAGED_STATUS_PREFIX, };
+// Shape helpers
+export function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * A valid settings container is an object; when `hooks` is present it MUST be
+ * an object; when `hooks.PreToolUse` is present it MUST be an array. Anything
+ * else is malformed.
+ */
+export function validateSettingsShape(parsed) {
+    if (!isPlainObject(parsed))
+        return false;
+    const { hooks } = parsed;
+    if (hooks !== undefined && !isPlainObject(hooks))
+        return false;
+    const pre = isPlainObject(hooks) ? hooks.PreToolUse : undefined;
+    if (pre !== undefined && !Array.isArray(pre))
+        return false;
+    return true;
+}
+// Canonical identity (Decision ②)
+const ASSET_SHA_TOKEN = /^[0-9a-f]{64}$/;
+const VERSION_PATTERN = /^javi-forge-global-pretooluse:v(\d+):sha256:/;
+/**
+ * Replace the trailing 64-hex asset SHA token in a managed `statusMessage` with
+ * the fixed placeholder so settings identity is invariant under asset rotation.
+ * A non-managed or malformed token is returned unchanged so it hashes to a
+ * distinct (non-current) value.
+ */
+export function normalizeStatusMessage(statusMessage) {
+    if (typeof statusMessage !== "string")
+        return "";
+    if (!statusMessage.startsWith(MANAGED_STATUS_PREFIX))
+        return statusMessage;
+    const token = statusMessage.slice(MANAGED_STATUS_PREFIX.length);
+    return ASSET_SHA_TOKEN.test(token)
+        ? `${MANAGED_STATUS_PREFIX}${ASSET_SHA_PLACEHOLDER}`
+        : statusMessage;
+}
+/** Parse the marker version (`…:v1:…` → 1) for diagnostics only. */
+export function parseVersionFromStatus(statusMessage) {
+    if (typeof statusMessage !== "string")
+        return undefined;
+    const match = VERSION_PATTERN.exec(statusMessage);
+    return match ? Number(match[1]) : undefined;
+}
+/**
+ * Canonicalize the marker-proven handler group into deterministic bytes and its
+ * SHA-256. Fixed key order (`type,command,args,timeout,statusMessage` inside a
+ * `matcher,hooks` group), the asset-SHA token normalized out, two-space indent
+ * plus a trailing newline. Only the single handler participates.
+ */
+export function canonicalizeSettingsEntry(group, handler) {
+    const h = isPlainObject(handler) ? handler : {};
+    const g = isPlainObject(group) ? group : {};
+    const canonicalHandler = {
+        type: h.type,
+        command: h.command,
+        args: h.args,
+        timeout: h.timeout,
+        statusMessage: normalizeStatusMessage(h.statusMessage),
+    };
+    const canonicalGroup = { matcher: g.matcher, hooks: [canonicalHandler] };
+    const serialization = `${JSON.stringify(canonicalGroup, null, 2)}\n`;
+    const canonicalSha256 = createHash("sha256")
+        .update(serialization, "utf8")
+        .digest("hex");
+    return { serialization, canonicalSha256 };
+}
+// Legacy recognition (deep structural equality only)
+/**
+ * Order-sensitive for arrays, key-set-exact (order-insensitive) for objects,
+ * strict for scalars. No substring, normalization, or tolerance.
+ */
+export function deepStructuralEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) || Array.isArray(b)) {
+        if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) {
+            return false;
+        }
+        return a.every((item, index) => deepStructuralEqual(item, b[index]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const keysA = Object.keys(a);
+        const keysB = Object.keys(b);
+        if (keysA.length !== keysB.length)
+            return false;
+        return keysA.every((key) => Object.hasOwn(b, key) && deepStructuralEqual(a[key], b[key]));
+    }
+    return false;
+}
+function countDeepMatches(target, list) {
+    let count = 0;
+    for (const item of list)
+        if (deepStructuralEqual(target, item))
+            count++;
+    return count;
+}
+/**
+ * In-object legacy recognition: exactly one deep-equal match for each of the
+ * four cohort objects (L1–L3 Pre, L4 Post) is `exact-legacy`; a partial,
+ * duplicate, or edited cohort is `foreign` (partial-legacy); unrecognized
+ * PreToolUse handler content is `foreign` per spec R2; only a container with no
+ * PreToolUse handler content is `absent` (installable). Whole-file SHA legacy is
+ * decided by the manager, which holds the raw bytes. (Spec R2 overrides
+ * design.md Algorithm C, which returns `absent` for the no-cohort fallthrough
+ * and so cannot flag a resembling unmarked handler.)
+ */
+export function classifyLegacy(parsed) {
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    const pre = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const post = isPlainObject(hooks) && Array.isArray(hooks.PostToolUse)
+        ? hooks.PostToolUse
+        : [];
+    const counts = [
+        countDeepMatches(LEGACY_COHORT.L1, pre),
+        countDeepMatches(LEGACY_COHORT.L2, pre),
+        countDeepMatches(LEGACY_COHORT.L3, pre),
+        countDeepMatches(LEGACY_COHORT.L4, post),
+    ];
+    if (counts.every((count) => count === 1)) {
+        return { state: "exact-legacy", detail: "cohort" };
+    }
+    if (counts.some((count) => count >= 1)) {
+        return { state: "foreign", detail: "partial-legacy" };
+    }
+    const preHandlers = pre.reduce((total, group) => total +
+        (isPlainObject(group) && Array.isArray(group.hooks)
+            ? group.hooks.length
+            : 0), 0);
+    if (preHandlers > 0)
+        return { state: "foreign", detail: "no-marker" };
+    return { state: "absent" };
+}
+function findManagedMarkers(groups) {
+    const markers = [];
+    for (let groupIndex = 0; groupIndex < groups.length; groupIndex++) {
+        const group = groups[groupIndex];
+        const handlers = isPlainObject(group) && Array.isArray(group.hooks) ? group.hooks : [];
+        for (let handlerIndex = 0; handlerIndex < handlers.length; handlerIndex++) {
+            const handler = handlers[handlerIndex];
+            if (isPlainObject(handler) &&
+                typeof handler.statusMessage === "string" &&
+                handler.statusMessage.startsWith(MANAGED_STATUS_PREFIX)) {
+                markers.push({ groupIndex, handlerIndex, group, handler });
+            }
+        }
+    }
+    return markers;
+}
+function isValidMatcherGroup(group) {
+    return (isPlainObject(group) &&
+        typeof group.matcher === "string" &&
+        Array.isArray(group.hooks));
+}
+/**
+ * Reduce a parsed settings container to one component state, from parsed
+ * structure only. Shape validation first, then marker-driven identity (always
+ * recomputed), then the legacy fallback when no marker is present.
+ */
+export function classifySettingsEntry(parsed, _currentAssetSha, identities) {
+    if (!validateSettingsShape(parsed))
+        return { state: "malformed" };
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    const groups = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const markers = findManagedMarkers(groups);
+    if (markers.length > 1) {
+        return { state: "edited-managed", detail: "multiple markers" };
+    }
+    if (markers.length === 0)
+        return classifyLegacy(parsed);
+    const marker = markers[0];
+    if (!isValidMatcherGroup(marker.group)) {
+        return { state: "edited-managed", detail: "marker in invalid container" };
+    }
+    const { canonicalSha256 } = canonicalizeSettingsEntry(marker.group, marker.handler);
+    const version = parseVersionFromStatus(marker.handler.statusMessage);
+    const base = {
+        version,
+        canonicalSha256,
+        groupIndex: marker.groupIndex,
+        handlerIndex: marker.handlerIndex,
+    };
+    if (identities.current &&
+        canonicalSha256 === identities.current.canonicalSha256) {
+        return { state: "managed-current", ...base };
+    }
+    if (identities.historical.some((entry) => entry.canonicalSha256 === canonicalSha256)) {
+        return { state: "released-outdated", ...base };
+    }
+    return { state: "edited-managed", ...base };
+}
+function groupHandlerCount(parsed, groupIndex) {
+    const hooks = isPlainObject(parsed) ? parsed.hooks : undefined;
+    const groups = isPlainObject(hooks) && Array.isArray(hooks.PreToolUse)
+        ? hooks.PreToolUse
+        : [];
+    const group = groups[groupIndex];
+    return isPlainObject(group) && Array.isArray(group.hooks)
+        ? group.hooks.length
+        : 0;
+}
+/**
+ * Plan removal of the marker-proven managed handler. Only a recognized managed
+ * identity (`managed-current` or `released-outdated`) is eligible; foreign,
+ * partial-legacy, edited-managed, and every non-regular state refuse.
+ */
+export function planManagedClaudeHookRemoval(parsed, currentAssetSha, identities) {
+    const cls = classifySettingsEntry(parsed, currentAssetSha, identities);
+    if (cls.state === "managed-current" || cls.state === "released-outdated") {
+        const handlerCount = groupHandlerCount(parsed, cls.groupIndex ?? -1);
+        const preservedSiblings = Math.max(handlerCount - 1, 0);
+        return {
+            refused: false,
+            state: cls.state,
+            groupIndex: cls.groupIndex,
+            handlerIndex: cls.handlerIndex,
+            removeGroup: preservedSiblings === 0,
+            preservedSiblings,
+        };
+    }
+    return {
+        refused: true,
+        reason: `refuse removal for state ${cls.state}`,
+        state: cls.state,
+    };
+}
+/**
+ * Plan the managed merge. `absent` installs a new group, `managed-current` is a
+ * no-op, `released-outdated` replaces the marked handler in place (siblings
+ * preserved), and every other state refuses (edited/force is a Slice-3 concern).
+ */
+export function planManagedClaudeHookMerge(parsed, currentAssetSha, identities) {
+    const cls = classifySettingsEntry(parsed, currentAssetSha, identities);
+    if (cls.state === "absent") {
+        return { refused: false, state: cls.state, action: "install" };
+    }
+    if (cls.state === "managed-current") {
+        return {
+            refused: false,
+            state: cls.state,
+            action: "noop",
+            groupIndex: cls.groupIndex,
+            handlerIndex: cls.handlerIndex,
+        };
+    }
+    if (cls.state === "released-outdated") {
+        const preservedSiblings = Math.max(groupHandlerCount(parsed, cls.groupIndex ?? -1) - 1, 0);
+        return {
+            refused: false,
+            state: cls.state,
+            action: "replace",
+            groupIndex: cls.groupIndex,
+            handlerIndex: cls.handlerIndex,
+            preservedSiblings,
+        };
+    }
+    return {
+        refused: true,
+        reason: `refuse merge for state ${cls.state}`,
+        state: cls.state,
+        action: "refuse",
+    };
+}
+//# sourceMappingURL=claude-hook-settings.js.map

package/dist/lib/plugin.d.ts

@@ -14,6 +14,14 @@ export declare function installPlugin(source: string, options?: {
     success: boolean;
     name?: string;
     error?: string;
+    /**
+     * FU-1 (R4-002): true when the failure is a skillguard gate refusal
+     * (manifest-integrity or verdict refusal, incl. a scanner-error deny).
+     * The CLI layer turns this into a non-zero exit code so scripted
+     * consumers can tell a refusal apart from success. Plain usage errors
+     * (invalid source, validation failed) leave it unset.
+     */
+    refused?: boolean;
 }>;
 /**
  * Remove an installed plugin by name.