@indigoai-us/hq-cli 5.98.3 → 5.99.1

package/dist/lib/doctor/__testing__/fake-hq-tree.js

@@ -0,0 +1,357 @@
+/**
+ * buildFakeHqTree — a reusable test harness that materialises a fake HQ tree in
+ * the OS temp directory from a declarative spec.
+ *
+ * Every `hq doctor` check is fundamentally a function of the on-disk shape of an
+ * HQ tree: which hooks exist, whether they are executable, whether they are
+ * registered in settings, which `hook-gate.sh` profiles list them, and whether
+ * the Codex mirror still matches its Claude original. This helper lets a test
+ * declare that shape — including its deliberately-broken variants — and get back
+ * a throwaway tree plus a manifest describing exactly what was written, without
+ * ever touching the real HQ tree.
+ *
+ * Design notes:
+ *   - Everything is written under a `mkdtempSync` root inside `os.tmpdir()`. The
+ *     real HQ tree is never read or written.
+ *   - The root path is canonicalised with `realpathSync` so callers can assert
+ *     containment under the temp dir on platforms (macOS) where the temp dir is
+ *     a symlink (`/var` -> `/private/var`).
+ *   - Cleanup is automatic: the first build registers a single `process` exit
+ *     handler that removes every tracked root, so nothing survives a test run,
+ *     including on test failure. `tree.cleanup()` is also exposed for eager
+ *     removal, and is idempotent.
+ *
+ * The reference for this pattern is core/scripts/test-codex-hook-adapter.sh,
+ * which stands up a throwaway HQ tree with `mktemp -d` and stubbed hook scripts.
+ */
+import { spawnSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+/** Canonical ordering of the gate profiles. */
+export const GATE_PROFILES = [
+    "minimal",
+    "standard",
+    "strict",
+];
+const DEFAULT_HOOK_BODY = "#!/bin/bash\ncat >/dev/null\nexit 0\n";
+const EXECUTABLE_MODE = 0o755;
+const NON_EXECUTABLE_MODE = 0o644;
+const DEFAULT_PREFIX = "hq-doctor-fake-";
+// --- Automatic cleanup registry ------------------------------------------------
+const trackedRoots = new Set();
+let exitHandlerRegistered = false;
+/** Remove every fake HQ tree still on disk. Safe to call repeatedly. */
+export function cleanupAllFakeHqTrees() {
+    for (const root of trackedRoots) {
+        removeTree(root);
+    }
+    trackedRoots.clear();
+}
+/** The set of tree roots this process is still tracking for cleanup. */
+export function trackedFakeHqTreeRoots() {
+    return [...trackedRoots];
+}
+function removeTree(root) {
+    try {
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+    catch {
+        // Best-effort: never let cleanup throw and mask a test's real failure.
+    }
+}
+/**
+ * Register a single process-exit handler that sweeps every tracked root. Bound
+ * once (guarded by a module flag) so repeated builds do not pile up listeners.
+ * `exit` fires on normal completion and after a failed test run alike, which is
+ * what guarantees no temp dir survives.
+ */
+function ensureExitHandler() {
+    if (exitHandlerRegistered)
+        return;
+    exitHandlerRegistered = true;
+    process.on("exit", cleanupAllFakeHqTrees);
+}
+// --- Builder -------------------------------------------------------------------
+/**
+ * Materialise a fake HQ tree from `spec` and return its root, manifest, and a
+ * cleanup handle. The tree lives under `os.tmpdir()` and is swept automatically
+ * when the process exits.
+ */
+export function buildFakeHqTree(spec = {}) {
+    ensureExitHandler();
+    const prefix = spec.prefix ?? DEFAULT_PREFIX;
+    const root = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix)));
+    trackedRoots.add(root);
+    const claudeHooksDir = path.join(root, ".claude", "hooks");
+    const codexHooksDir = path.join(root, ".codex", "hooks");
+    fs.mkdirSync(claudeHooksDir, { recursive: true });
+    fs.mkdirSync(codexHooksDir, { recursive: true });
+    // A `core/` directory is what marks this as an HQ tree for later root
+    // discovery; cheap to add and keeps the fixture realistic.
+    fs.mkdirSync(path.join(root, "core", "scripts"), { recursive: true });
+    const hookSpecs = spec.hooks ?? [];
+    const hookEntries = hookSpecs.map((hook) => writeHook(claudeHooksDir, codexHooksDir, hook));
+    // hook-gate.sh (mirrored to both platforms) carries the three profile lists,
+    // aggregated across every hook's `profiles`.
+    const gateSource = renderHookGate(hookEntries);
+    const claudeHookGatePath = path.join(claudeHooksDir, "hook-gate.sh");
+    const codexHookGatePath = path.join(codexHooksDir, "hook-gate.sh");
+    writeScript(claudeHookGatePath, gateSource, EXECUTABLE_MODE);
+    writeScript(codexHookGatePath, gateSource, EXECUTABLE_MODE);
+    const claudeSettingsPath = path.join(root, ".claude", "settings.json");
+    fs.writeFileSync(claudeSettingsPath, JSON.stringify(renderClaudeSettings(hookEntries, spec.claudeSettings), null, 2) + "\n");
+    const codexHooksJsonPath = path.join(root, ".codex", "hooks.json");
+    fs.writeFileSync(codexHooksJsonPath, JSON.stringify(renderCodexHooksJson(root, hookEntries), null, 2) + "\n");
+    const grok = writeGrok(root, spec.grok);
+    let gitInitialised = false;
+    if (spec.git) {
+        gitInitialised = initGitRepo(root);
+    }
+    const manifest = {
+        root,
+        claudeSettingsPath,
+        claudeHooksDir,
+        claudeHookGatePath,
+        codexHooksJsonPath,
+        codexHooksDir,
+        codexHookGatePath,
+        grokDir: grok.dir,
+        grokAdapterPath: grok.adapterPath,
+        grokRegistrationPath: grok.registrationPath,
+        grokBridgeInstalled: grok.bridgeInstalled,
+        gitInitialised,
+        hooks: hookEntries,
+    };
+    let cleaned = false;
+    const cleanup = () => {
+        if (cleaned)
+            return;
+        cleaned = true;
+        removeTree(root);
+        trackedRoots.delete(root);
+    };
+    return {
+        root,
+        manifest,
+        path: (...segments) => path.join(root, ...segments),
+        cleanup,
+    };
+}
+// --- Hook materialisation ------------------------------------------------------
+function writeHook(claudeHooksDir, codexHooksDir, hook) {
+    const claudeBody = hook.body ?? DEFAULT_HOOK_BODY;
+    const present = hook.present !== false;
+    const registered = hook.registered !== false;
+    const events = hook.events ?? ["PreToolUse"];
+    const profiles = hook.profiles ?? [...GATE_PROFILES];
+    const scriptPath = path.join(claudeHooksDir, `${hook.id}.sh`);
+    let mode = null;
+    let executable = false;
+    if (present) {
+        const targetMode = resolveMode(hook.mode, hook.executable);
+        writeScript(scriptPath, claudeBody, targetMode);
+        mode = statMode(scriptPath);
+        executable = isExecutable(mode);
+    }
+    const codex = writeCodexMirror(codexHooksDir, hook, claudeBody);
+    return {
+        id: hook.id,
+        scriptPath,
+        present,
+        mode,
+        executable,
+        registered,
+        events,
+        matcher: hook.matcher ?? null,
+        profiles,
+        codex,
+    };
+}
+function writeCodexMirror(codexHooksDir, hook, claudeBody) {
+    // `codex: false` => a Claude hook with no Codex counterpart.
+    if (hook.codex === false)
+        return null;
+    const codexSpec = hook.codex ?? {};
+    const present = codexSpec.present !== false;
+    const registered = codexSpec.registered !== false;
+    const body = codexSpec.body ?? claudeBody;
+    const drifted = body !== claudeBody;
+    const scriptPath = path.join(codexHooksDir, `${hook.id}.sh`);
+    let mode = null;
+    let executable = false;
+    if (present) {
+        const targetMode = resolveMode(codexSpec.mode, codexSpec.executable);
+        writeScript(scriptPath, body, targetMode);
+        mode = statMode(scriptPath);
+        executable = isExecutable(mode);
+    }
+    return { scriptPath, present, mode, executable, registered, drifted };
+}
+function renderClaudeSettings(hooks, extra) {
+    const events = {};
+    for (const hook of hooks) {
+        if (!hook.registered)
+            continue;
+        const command = `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/hook-gate.sh" ${hook.id} ` +
+            `"$CLAUDE_PROJECT_DIR/.claude/hooks/${hook.id}.sh"`;
+        for (const event of hook.events) {
+            (events[event] ??= []).push(makeSettingsEntry(command, hook.matcher ?? undefined));
+        }
+    }
+    return { ...extra, hooks: events };
+}
+function renderCodexHooksJson(root, hooks) {
+    const events = {};
+    for (const hook of hooks) {
+        if (!hook.codex || !hook.codex.registered)
+            continue;
+        const gate = `${root}/.codex/hooks/hook-gate.sh`;
+        const script = `${root}/.codex/hooks/${hook.id}.sh`;
+        const command = `'${gate}' ${hook.id} '${script}'`;
+        for (const event of hook.events) {
+            (events[event] ??= []).push(makeSettingsEntry(command, hook.matcher ?? undefined));
+        }
+    }
+    return { hooks: events };
+}
+function makeSettingsEntry(command, matcher) {
+    const entry = {
+        hooks: [{ type: "command", command, timeout: 5 }],
+    };
+    if (matcher)
+        entry.matcher = matcher;
+    return entry;
+}
+/**
+ * Render a self-contained `hook-gate.sh` whose three profile functions list the
+ * hook ids assigned to each profile, modelled on the real gate in
+ * `.claude/hooks/hook-gate.sh`. Self-contained so the fixture never has to
+ * source the real HQ tree.
+ */
+function renderHookGate(hooks) {
+    const byProfile = {
+        minimal: [],
+        standard: [],
+        strict: [],
+    };
+    for (const hook of hooks) {
+        for (const profile of hook.profiles) {
+            byProfile[profile].push(hook.id);
+        }
+    }
+    const fns = GATE_PROFILES.map((profile) => renderProfileFunction(profile, byProfile[profile])).join("\n\n");
+    return `#!/bin/bash
+# Fake hook-gate.sh generated by buildFakeHqTree (test fixture — not the real gate).
+set -euo pipefail
+
+if [ $# -lt 2 ]; then
+  echo "USAGE: hook-gate.sh <hook-id> <actual-hook-script> [args...]" >&2
+  exit 1
+fi
+
+HOOK_ID="$1"
+HOOK_SCRIPT="$2"
+shift 2
+
+PROFILE="\${HQ_HOOK_PROFILE:-standard}"
+
+${fns}
+
+should_run=0
+case "$PROFILE" in
+  minimal)
+    if is_in_minimal_profile "$HOOK_ID"; then should_run=1; fi
+    ;;
+  standard)
+    if is_in_standard_profile "$HOOK_ID"; then should_run=1; fi
+    ;;
+  strict)
+    if is_in_strict_profile "$HOOK_ID"; then should_run=1; fi
+    ;;
+  *)
+    echo "ERROR: Unknown profile '$PROFILE'. Use minimal|standard|strict" >&2
+    exit 1
+    ;;
+esac
+
+if [ "$should_run" -eq 0 ]; then
+  exit 0
+fi
+
+exec "$HOOK_SCRIPT" "$@"
+`;
+}
+function renderProfileFunction(profile, ids) {
+    const caseBlock = ids.length > 0 ? `    ${ids.join("|")})\n      return 0\n      ;;\n` : "";
+    return `is_in_${profile}_profile() {
+  case "$1" in
+${caseBlock}    *)
+      return 1
+      ;;
+  esac
+}`;
+}
+function writeGrok(root, spec) {
+    const absent = {
+        dir: null,
+        adapterPath: null,
+        registrationPath: null,
+        bridgeInstalled: false,
+    };
+    if (spec === false)
+        return absent;
+    const grokSpec = spec ?? {};
+    if (grokSpec.present === false)
+        return absent;
+    const dir = path.join(root, ".grok", "hooks");
+    fs.mkdirSync(dir, { recursive: true });
+    const adapterPath = path.join(dir, "hq-grok-hook-adapter.sh");
+    writeScript(adapterPath, "#!/bin/bash\ncat >/dev/null\nexit 0\n", grokSpec.adapterExecutable === false ? NON_EXECUTABLE_MODE : EXECUTABLE_MODE);
+    const registrationPath = path.join(dir, "hq-grok.json");
+    const registration = {
+        hooks: {
+            PreToolUse: [
+                {
+                    hooks: [
+                        { type: "command", command: "./hq-grok-hook-adapter.sh", timeout: 30 },
+                    ],
+                },
+            ],
+        },
+    };
+    fs.writeFileSync(registrationPath, JSON.stringify(registration, null, 2) + "\n");
+    return {
+        dir,
+        adapterPath,
+        registrationPath,
+        bridgeInstalled: grokSpec.bridgeInstalled !== false,
+    };
+}
+// --- git -----------------------------------------------------------------------
+function initGitRepo(root) {
+    // Seed a git repo the way the reference harness does, without shelling out
+    // for identity config: write it straight into .git/config.
+    const res = spawnSync("git", ["init", "-q", "-b", "main"], { cwd: root });
+    if (res.status !== 0)
+        return false;
+    fs.appendFileSync(path.join(root, ".git", "config"), "[user]\n\temail = fake-hq-tree@example.com\n\tname = fake-hq-tree\n[commit]\n\tgpgsign = false\n");
+    return true;
+}
+// --- Low-level helpers ---------------------------------------------------------
+function resolveMode(explicit, executable) {
+    if (explicit !== undefined)
+        return explicit & 0o777;
+    return executable === false ? NON_EXECUTABLE_MODE : EXECUTABLE_MODE;
+}
+function writeScript(target, body, mode) {
+    fs.writeFileSync(target, body);
+    fs.chmodSync(target, mode);
+}
+function statMode(target) {
+    return fs.statSync(target).mode & 0o777;
+}
+function isExecutable(mode) {
+    return mode !== null && (mode & 0o111) !== 0;
+}
+//# sourceMappingURL=fake-hq-tree.js.map

package/dist/lib/doctor/allowed-divergence.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The allowed-divergence list — the doctor's suppression list for known,
+ * intentional differences between a Codex mirror and its Claude original.
+ *
+ * Claude and Grok both execute the canonical `.claude/hooks/` scripts; only
+ * Codex runs duplicated copies, so the Codex mirror is the entire drift surface
+ * (US-005). Most drift is a bug the doctor must FAIL on — but a handful of
+ * mirrors legitimately differ (a Codex payload shape, an adapter shim). Those
+ * are declared here so the doctor can suppress the FAIL, *provided every entry
+ * carries a human reason*.
+ *
+ * The list is discovered at runtime from the HQ tree at
+ * `core/hook-tests/allowed-divergence.yaml`, not baked into the CLI, so a hook
+ * and its allowed-divergence note ship in the same hq-core commit. The file is
+ * optional: an absent list simply allows no divergences. Two guard rails keep
+ * the list honest and are enforced by the Codex wiring check that consumes this
+ * module:
+ *   - an entry with no `reason` is rejected (reported WARN), and
+ *   - an entry whose file no longer differs is reported WARN as *stale*, so the
+ *     list cannot silently rot into suppressing drift that has since changed.
+ */
+/** Location of the allowed-divergence list, relative to the HQ tree root. */
+export declare const ALLOWED_DIVERGENCE_RELPATH: string;
+/** One valid allowed-divergence entry. */
+export interface AllowedDivergenceEntry {
+    /** Hook filename this entry suppresses, normalised to a `<id>.sh` basename. */
+    file: string;
+    /** Required, non-empty human reason the divergence is intentional. */
+    reason: string;
+}
+/** A rejected entry — bad shape, missing file, or missing reason. */
+export interface AllowedDivergenceProblem {
+    /** The offending file basename, when one could be identified. */
+    file: string | null;
+    /** Why the entry was rejected. */
+    message: string;
+}
+/** The parsed allowed-divergence list plus every entry it rejected. */
+export interface AllowedDivergenceLoad {
+    /** Absolute path the list was read from (whether or not it exists). */
+    path: string;
+    /** Whether the YAML file exists on disk. */
+    present: boolean;
+    /** Valid entries; each carries a non-empty `reason`. */
+    entries: AllowedDivergenceEntry[];
+    /** Malformed entries — missing reason, missing file, or a bad shape. */
+    problems: AllowedDivergenceProblem[];
+}
+/** Absolute path to the allowed-divergence list for `hqRoot`. */
+export declare function allowedDivergencePath(hqRoot: string): string;
+/**
+ * Normalise a hook reference to a `<id>.sh` basename so entries written as
+ * `detect-secrets`, `detect-secrets.sh`, or `.codex/hooks/detect-secrets.sh`
+ * all match the same on-disk file.
+ */
+export declare function normaliseHookFile(file: string): string;
+/**
+ * Read and parse the allowed-divergence list for `hqRoot`. An absent file is
+ * not an error — it yields `present: false` with no entries and no problems,
+ * because a tree that has declared no divergences is a valid, healthy state.
+ */
+export declare function loadAllowedDivergence(hqRoot: string): AllowedDivergenceLoad;
+/**
+ * Parse allowed-divergence YAML into valid entries and rejected problems.
+ * Accepts either a top-level list of `{file, reason}` mappings or an object
+ * carrying that list under `divergences` / `allowed` / `entries`.
+ */
+export declare function parseAllowedDivergence(source: string): {
+    entries: AllowedDivergenceEntry[];
+    problems: AllowedDivergenceProblem[];
+};
+//# sourceMappingURL=allowed-divergence.d.ts.map

package/dist/lib/doctor/allowed-divergence.js

@@ -0,0 +1,134 @@
+/**
+ * The allowed-divergence list — the doctor's suppression list for known,
+ * intentional differences between a Codex mirror and its Claude original.
+ *
+ * Claude and Grok both execute the canonical `.claude/hooks/` scripts; only
+ * Codex runs duplicated copies, so the Codex mirror is the entire drift surface
+ * (US-005). Most drift is a bug the doctor must FAIL on — but a handful of
+ * mirrors legitimately differ (a Codex payload shape, an adapter shim). Those
+ * are declared here so the doctor can suppress the FAIL, *provided every entry
+ * carries a human reason*.
+ *
+ * The list is discovered at runtime from the HQ tree at
+ * `core/hook-tests/allowed-divergence.yaml`, not baked into the CLI, so a hook
+ * and its allowed-divergence note ship in the same hq-core commit. The file is
+ * optional: an absent list simply allows no divergences. Two guard rails keep
+ * the list honest and are enforced by the Codex wiring check that consumes this
+ * module:
+ *   - an entry with no `reason` is rejected (reported WARN), and
+ *   - an entry whose file no longer differs is reported WARN as *stale*, so the
+ *     list cannot silently rot into suppressing drift that has since changed.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as yaml from "js-yaml";
+/** Location of the allowed-divergence list, relative to the HQ tree root. */
+export const ALLOWED_DIVERGENCE_RELPATH = path.join("core", "hook-tests", "allowed-divergence.yaml");
+/** Absolute path to the allowed-divergence list for `hqRoot`. */
+export function allowedDivergencePath(hqRoot) {
+    return path.join(hqRoot, ALLOWED_DIVERGENCE_RELPATH);
+}
+/**
+ * Normalise a hook reference to a `<id>.sh` basename so entries written as
+ * `detect-secrets`, `detect-secrets.sh`, or `.codex/hooks/detect-secrets.sh`
+ * all match the same on-disk file.
+ */
+export function normaliseHookFile(file) {
+    const base = path.basename(String(file).trim());
+    return base.endsWith(".sh") ? base : `${base}.sh`;
+}
+/**
+ * Read and parse the allowed-divergence list for `hqRoot`. An absent file is
+ * not an error — it yields `present: false` with no entries and no problems,
+ * because a tree that has declared no divergences is a valid, healthy state.
+ */
+export function loadAllowedDivergence(hqRoot) {
+    const filePath = allowedDivergencePath(hqRoot);
+    let source;
+    try {
+        source = fs.readFileSync(filePath, "utf8");
+    }
+    catch {
+        return { path: filePath, present: false, entries: [], problems: [] };
+    }
+    const parsed = parseAllowedDivergence(source);
+    return { path: filePath, present: true, ...parsed };
+}
+/**
+ * Parse allowed-divergence YAML into valid entries and rejected problems.
+ * Accepts either a top-level list of `{file, reason}` mappings or an object
+ * carrying that list under `divergences` / `allowed` / `entries`.
+ */
+export function parseAllowedDivergence(source) {
+    const entries = [];
+    const problems = [];
+    let doc;
+    try {
+        doc = yaml.load(source);
+    }
+    catch (error) {
+        problems.push({
+            file: null,
+            message: `allowed-divergence.yaml is not valid YAML: ${error.message}`,
+        });
+        return { entries, problems };
+    }
+    const rawList = extractList(doc);
+    if (rawList === null) {
+        // An empty document (null / undefined) legitimately allows no divergences.
+        // Any other non-list shape is a mistake worth surfacing.
+        if (doc !== null && doc !== undefined) {
+            problems.push({
+                file: null,
+                message: "allowed-divergence.yaml must be a list of {file, reason} entries, or an object with a `divergences` list.",
+            });
+        }
+        return { entries, problems };
+    }
+    for (const item of rawList) {
+        if (!item || typeof item !== "object" || Array.isArray(item)) {
+            problems.push({
+                file: null,
+                message: "allowed-divergence entry must be a mapping with `file` and `reason`.",
+            });
+            continue;
+        }
+        const record = item;
+        const rawFile = record.file;
+        const file = typeof rawFile === "string" && rawFile.trim()
+            ? normaliseHookFile(rawFile)
+            : null;
+        if (!file) {
+            problems.push({
+                file: null,
+                message: "allowed-divergence entry is missing a `file`.",
+            });
+            continue;
+        }
+        const rawReason = record.reason;
+        if (typeof rawReason !== "string" || !rawReason.trim()) {
+            problems.push({
+                file,
+                message: `allowed-divergence entry for ${file} is missing a required \`reason\`.`,
+            });
+            continue;
+        }
+        entries.push({ file, reason: rawReason.trim() });
+    }
+    return { entries, problems };
+}
+/** Pull the entry list out of whichever supported top-level shape was used. */
+function extractList(doc) {
+    if (Array.isArray(doc))
+        return doc;
+    if (doc && typeof doc === "object") {
+        const record = doc;
+        for (const key of ["divergences", "allowed", "allowedDivergences", "entries"]) {
+            const value = record[key];
+            if (Array.isArray(value))
+                return value;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=allowed-divergence.js.map

package/dist/lib/doctor/checks/claude-wiring.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Claude Code hook WIRING checks (US-004).
+ *
+ * "Wiring" is everything short of firing the hook: is every registration backed
+ * by a script that exists and is executable, is every script on disk actually
+ * registered, is every gated hook id a member of all three `hook-gate.sh`
+ * profiles, and does any command word-split its own script path. A hook can be
+ * present, correct, and completely dead — this check catches the ways that
+ * happens without a single error surfacing to the user.
+ *
+ * It is strictly read-only: it stats and reads files and never writes, so a
+ * doctor run is byte-identical to no run at all (asserted by test).
+ *
+ * The unquoted-`$CLAUDE_PROJECT_DIR` detection is a faithful TypeScript port of
+ * the quote-aware shell tokenizer in `core/scripts/lib/hook-command-scan.sh`
+ * (used by `core/scripts/check-hq-hooks.sh`), not a reinvention: Claude Code
+ * runs each hook command through `/bin/sh`, so an expansion outside double
+ * quotes is word-split, and on an install root containing whitespace the shell
+ * execs a truncated path and every such hook dies as an invisible non-blocking
+ * error. Sharing the tokenizer's semantics is the point — a quoted form such as
+ * `"$CLAUDE_PROJECT_DIR/x"` or `"${CLAUDE_PROJECT_DIR}/x"` must never be called
+ * broken, and an unquoted one must never be missed.
+ */
+import type { CheckContext, CheckResult } from "../types.js";
+/** Common id prefix for every result this check family emits. */
+export declare const CLAUDE_WIRING_PREFIX = "hooks.claude";
+/**
+ * Run every Claude wiring check against the resolved HQ tree and return the
+ * per-item results. Never throws on a malformed or partial tree — a missing or
+ * unreadable input contributes a result (or nothing), not an exception.
+ */
+export declare function checkClaudeWiring(context: CheckContext): CheckResult[];
+/** The result of quote-aware analysis of one hook command string. */
+export interface CommandScan {
+    /**
+     * True when $CLAUDE_PROJECT_DIR expands OUTSIDE double quotes anywhere in the
+     * command — the one form `/bin/sh` word-splits.
+     */
+    unquotedProjectDir: boolean;
+    /**
+     * Relative paths (to the HQ root) the command actually EXECUTES: the
+     * interpreter's script argument, plus the delegated script when that
+     * entrypoint is hook-gate.sh. Guarded optional paths and data arguments are
+     * deliberately excluded — a missing optional file is not a broken install.
+     */
+    requiredRelpaths: string[];
+    /**
+     * The gated hook id, when the command routes through hook-gate.sh (its first
+     * bare argument), else null.
+     */
+    gatedHookId: string | null;
+}
+/** Quote-aware analysis of a single hook command. See {@link CommandScan}. */
+export declare function scanHookCommand(command: string): CommandScan;
+//# sourceMappingURL=claude-wiring.d.ts.map