@indigoai-us/hq-cli 5.117.2 → 5.117.3

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.117.3] — 2026-09-16
+
+### Fixed
+
+- `hq doctor --fix` no longer breaks Claude Code sessions. Since HQ moved to a single master hook, the doctor saw every hook script as unregistered. It then added one hook entry per script with no tool filter, so guards such as the Glob path check and core protection ran on every tool call and blocked Bash, Skill and Read with "Glob needs a path" or "Edit to locked path is not allowed". An HQ update could then move those entries into `.claude/settings.local.json`. The doctor no longer auto-registers orphan scripts. It now detects the stray entries in both settings files and `hq doctor --fix` removes them, keeping your permissions and any hooks you added yourself. Scripts listed in `.claude/hooks/hook-registry.json` also no longer show as orphans.
+
+### Fixed
+
+- `hq doctor` now keeps its hook-health compatibility verdict in step with
+  `check-hq-hooks.sh` when either required command hook is missing.
+
 ## [5.117.2] — 2026-09-16
 
 ### Fixed
@@ -26,6 +37,12 @@
   Workforce now. The free plan is called Starter rather than "free plan", to
   match the pricing page.
 
+### Fixed
+
+- `hq doctor` now reports failed hook wiring when `.claude/settings.json` has
+  no usable command hook for `SessionStart` or `PreToolUse`. The file can still
+  be present and valid JSON, but it no longer reads as healthy when nothing runs.
+
 ## [5.117.1] — 2026-09-16
 
 ### Fixed

package/dist/lib/doctor/__testing__/fake-hq-tree.d.ts

@@ -74,7 +74,7 @@ export interface FakeHookSpec {
     mode?: number;
     /** Whether the hook is registered in `.claude/settings.json`. Default: true. */
     registered?: boolean;
-    /** Events the hook registers against. Default: ["PreToolUse"]. */
+    /** Events the hook registers against. Default: SessionStart and PreToolUse. */
     events?: HookEventName[];
     /** Optional settings matcher (e.g. "Bash", "Glob"). */
     matcher?: string;

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

@@ -166,7 +166,7 @@ function writeHook(claudeHooksDir, codexHooksDir, hook, defaultMirror) {
     const claudeBody = hook.body ?? DEFAULT_HOOK_BODY;
     const present = hook.present !== false;
     const registered = hook.registered !== false;
-    const events = hook.events ?? ["PreToolUse"];
+    const events = hook.events ?? ["SessionStart", "PreToolUse"];
     const profiles = hook.profiles ?? [...GATE_PROFILES];
     const scriptPath = path.join(claudeHooksDir, `${hook.id}.sh`);
     let mode = null;

package/dist/lib/doctor/checks/claude-wiring.js

@@ -24,6 +24,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { GATE_PROFILES, gateMembership, parseHookGateProfiles, } from "../hook-gate-profiles.js";
+import { countStrayGateEntries } from "../stray-gate-entries.js";
 /** Common id prefix for every result this check family emits. */
 export const CLAUDE_WIRING_PREFIX = "hooks.claude";
 /**
@@ -57,6 +58,35 @@ export function checkClaudeWiring(context) {
     else if (local.present) {
         registrations.push(...enumerateRegistrations(local.value, ".claude/settings.local.json"));
     }
+    // --- Stray matcher-less gate entries (written by old `hq doctor --fix`) -------
+    // Only on master-hook trees: there, per-hook gate entries are never shipped,
+    // so a matcher-less one can only be the doctor-generated stray. A legacy tree
+    // that still registers hooks one by one is left alone.
+    const usesMasterHook = registrations.some((reg) => /\/master-hook\.sh\b/.test(reg.command));
+    for (const [file, parsed] of usesMasterHook ? [
+        ["settings.json", base],
+        ["settings.local.json", local],
+    ] : []) {
+        if (!parsed.present || parsed.invalid)
+            continue;
+        const abs = path.join(claudeDir, file);
+        const stray = countStrayGateEntries(parsed.value);
+        results.push(stray > 0
+            ? {
+                status: "FAIL",
+                checkId: `${CLAUDE_WIRING_PREFIX}.stray-gate-registration`,
+                target: abs,
+                message: `.claude/${file} has ${stray} hook-gate registration${stray === 1 ? "" : "s"} with no matcher. ` +
+                    "They run on every tool call and can block Bash, Skill and Read. An older `hq doctor --fix` wrote them.",
+                remediation: `Remove the matcher-less hook-gate.sh entries from .claude/${file} (hq doctor --fix does this).`,
+            }
+            : {
+                status: "PASS",
+                checkId: `${CLAUDE_WIRING_PREFIX}.stray-gate-registration`,
+                target: abs,
+                message: `.claude/${file} has no stray matcher-less hook-gate registrations.`,
+            });
+    }
     const scans = registrations.map((reg) => ({
         reg,
         scan: scanHookCommand(reg.command),
@@ -116,6 +146,11 @@ export function checkClaudeWiring(context) {
         for (const rp of scan.requiredRelpaths)
             referencedBasenames.add(baseName(rp));
     }
+    // master-hook.sh dispatches the gated hooks listed in hook-registry.json, so
+    // those scripts are registered even though no settings command names them.
+    for (const script of hookRegistryScripts(path.join(hooksDir, "hook-registry.json"))) {
+        referencedBasenames.add(baseName(script));
+    }
     for (const file of listShellScripts(hooksDir)) {
         if (referencedBasenames.has(file))
             continue;
@@ -124,7 +159,7 @@ export function checkClaudeWiring(context) {
             checkId: `${CLAUDE_WIRING_PREFIX}.orphan`,
             target: path.join(hooksDir, file),
             message: `Hook script ${file} is present in .claude/hooks/ but is not registered in any settings file.`,
-            remediation: `Register ${file} in .claude/settings.json or delete it.`,
+            remediation: `Add ${file} to .claude/hooks/hook-registry.json with the right event and matcher, or delete it.`,
         });
     }
     // --- AC4: every gated hook id is in ALL THREE profiles -----------------------
@@ -234,6 +269,31 @@ export function checkClaudeWiring(context) {
  * event in a parsed settings object. Tolerant of malformed shapes — any
  * non-conforming branch contributes nothing rather than throwing.
  */
+/** Every `script` path listed in .claude/hooks/hook-registry.json (empty when absent). */
+function hookRegistryScripts(registryPath) {
+    const parsed = readJsonFile(registryPath);
+    if (!parsed.present || parsed.invalid)
+        return [];
+    const hooks = parsed.value?.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return [];
+    const out = [];
+    for (const entries of Object.values(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            const inner = entry?.hooks;
+            if (!Array.isArray(inner))
+                continue;
+            for (const item of inner) {
+                const script = item?.script;
+                if (typeof script === "string" && script)
+                    out.push(script);
+            }
+        }
+    }
+    return out;
+}
 function enumerateRegistrations(settings, source) {
     const out = [];
     if (!settings || typeof settings !== "object")

package/dist/lib/doctor/compat.js

@@ -47,6 +47,7 @@ export const RUNTIME_ENFORCEMENT_CHECK_ID = "hooks.runtime.enforcement";
  */
 export const CHECK_HQ_HOOKS_SETTINGS_SCOPE = [
     "hooks.settings-present",
+    "hooks.settings-required-command-hooks",
     "hooks.settings-valid-json",
     "hooks.claude.settings-local-valid-json",
     "hooks.claude.unquoted-project-dir",

package/dist/lib/doctor/fix/apply.js

@@ -35,6 +35,7 @@ import { createDefaultRegistry } from "../registry.js";
 import { flattenFamilies } from "../report.js";
 import { gateMembership, parseHookGateProfiles, } from "../hook-gate-profiles.js";
 import { createBackup } from "./backup.js";
+import { removeStrayGateEntries } from "../stray-gate-entries.js";
 import { deriveRemediation } from "./remediation.js";
 /** The tree subtrees whose uncommitted changes block a `--fix` run. */
 export const HOOK_CONFIG_DIRS = [".claude", ".codex", ".grok"];
@@ -237,8 +238,8 @@ function planFix(hqRoot, result, rem, refreshSync) {
             return planExecutableBit(hqRoot, result, rem);
         case "gate-profile":
             return planGateProfile(hqRoot, result, rem);
-        case "register-hook":
-            return planRegisterHook(hqRoot, result, rem);
+        case "remove-stray-gate-entries":
+            return planRemoveStrayGateEntries(hqRoot, result, rem);
         case "refresh-sync":
             return planRefreshSync(hqRoot, result, rem, refreshSync);
         default:
@@ -328,34 +329,32 @@ function planGateProfile(hqRoot, result, rem) {
         postStatus: (results) => statusForTarget(results, ".gate-profiles", hookId),
     };
 }
-/** Re-register a script that is present on disk but wired in no settings file. */
-function planRegisterHook(hqRoot, result, rem) {
-    const scriptAbs = rem.fixTarget;
-    if (!scriptAbs)
+/** Remove matcher-less hook-gate.sh registrations an older doctor wrote. */
+function planRemoveStrayGateEntries(hqRoot, result, rem) {
+    const settingsPath = rem.fixTarget;
+    if (!settingsPath)
+        return null;
+    const current = readJson(settingsPath);
+    if (!current)
+        return null;
+    const { removed } = removeStrayGateEntries(current);
+    if (removed === 0)
         return null;
-    const settingsPath = path.join(hqRoot, ".claude", "settings.json");
-    const hookId = path.basename(scriptAbs).replace(/\.sh$/, "");
-    const event = "PreToolUse";
-    const command = `bash "$CLAUDE_PROJECT_DIR/.claude/hooks/hook-gate.sh" ${hookId} ` +
-        `"$CLAUDE_PROJECT_DIR/.claude/hooks/${hookId}.sh"`;
     const relpath = toRelpath(hqRoot, settingsPath);
     return {
         checkId: result.checkId,
-        fixClass: "register-hook",
-        target: scriptAbs,
+        fixClass: "remove-stray-gate-entries",
+        target: settingsPath,
         relpath,
         preview: `  ${relpath}\n` +
-            `    + hooks.${event}: register ${hookId} via hook-gate.sh\n` +
-            `      ${command}`,
-        summary: `register ${hookId} on ${event}`,
+            `    - ${removed} matcher-less hook-gate.sh registration${removed === 1 ? "" : "s"} (they fire on every tool call)`,
+        summary: `remove ${removed} stray hook registration${removed === 1 ? "" : "s"} from ${relpath}`,
         apply: () => {
-            const settings = readJson(settingsPath) ?? {};
-            const updated = registerHookInSettings(settings, event, command);
-            fs.writeFileSync(settingsPath, JSON.stringify(updated, null, 2) + "\n");
+            const latest = readJson(settingsPath) ?? {};
+            const cleaned = removeStrayGateEntries(latest).settings;
+            fs.writeFileSync(settingsPath, JSON.stringify(cleaned, null, 2) + "\n");
         },
-        // After registration the script becomes a wired, executable file, reported
-        // by the Claude wiring tier's `…script` PASS keyed on the same path.
-        postStatus: (results) => statusForPath(results, scriptAbs),
+        postStatus: (results) => statusForTarget(results, ".stray-gate-registration", settingsPath),
     };
 }
 // --- Shell / JSON edit primitives ---------------------------------------------

package/dist/lib/doctor/fix/remediation.d.ts

@@ -17,8 +17,11 @@
  *   - `gate-profile`    — add a gated hook id to the `hook-gate.sh` profile
  *                         allowlists it is missing from. Detected by the
  *                         `…gate-profiles` FAIL from the Claude wiring tier.
- *   - `register-hook`   — re-register a script that is present on disk but wired
- *                         nowhere. Detected by the `…orphan` WARN.
+ *   - `remove-stray-gate-entries` — delete matcher-less hook-gate.sh
+ *                         registrations an older `--fix` wrote into
+ *                         settings.json / settings.local.json. Detected by the
+ *                         `…stray-gate-registration` FAIL. (An orphan script is
+ *                         never auto-registered: that is what created them.)
  *   - `refresh-sync`    — run a targeted pull for a company journal that is
  *                         stale or never-synced AND has a local
  *                         `companies/<slug>` tree. Pull-only, `--on-conflict
@@ -35,7 +38,7 @@
  */
 import type { CheckResult } from "../types.js";
 /** The allowlisted safe repair classes `--fix` is permitted to apply. */
-export type FixClass = "executable-bit" | "gate-profile" | "register-hook" | "refresh-sync";
+export type FixClass = "executable-bit" | "gate-profile" | "remove-stray-gate-entries" | "refresh-sync";
 /**
  * A finding's structured remediation. `autoFixable`, `action`, and `command`
  * are the `--json` surface (AC1); `fixTarget`/`fixClass` are the internal handle
@@ -51,7 +54,7 @@ export interface Remediation {
     /** The safe class when {@link autoFixable}, else null (manual-only). */
     fixClass: FixClass | null;
     /**
-     * The concrete file path (exec-bit, register-hook) or hook id (gate-profile)
+     * The concrete file path (exec-bit, remove-stray-gate-entries) or hook id (gate-profile)
      * the auto-fix operates on. Present only when {@link autoFixable}. Internal —
      * deliberately omitted from the `--json` document.
      */

package/dist/lib/doctor/fix/remediation.js

@@ -17,8 +17,11 @@
  *   - `gate-profile`    — add a gated hook id to the `hook-gate.sh` profile
  *                         allowlists it is missing from. Detected by the
  *                         `…gate-profiles` FAIL from the Claude wiring tier.
- *   - `register-hook`   — re-register a script that is present on disk but wired
- *                         nowhere. Detected by the `…orphan` WARN.
+ *   - `remove-stray-gate-entries` — delete matcher-less hook-gate.sh
+ *                         registrations an older `--fix` wrote into
+ *                         settings.json / settings.local.json. Detected by the
+ *                         `…stray-gate-registration` FAIL. (An orphan script is
+ *                         never auto-registered: that is what created them.)
  *   - `refresh-sync`    — run a targeted pull for a company journal that is
  *                         stale or never-synced AND has a local
  *                         `companies/<slug>` tree. Pull-only, `--on-conflict
@@ -86,14 +89,19 @@ export function deriveRemediation(result) {
             command: remediation ?? `Add ${target} to the missing hook-gate.sh profiles.`,
         };
     }
-    // register-hook — a script on disk that no settings file references.
-    if (checkId.endsWith(".orphan") && target) {
+    // remove-stray-gate-entries — matcher-less hook-gate.sh registrations that an
+    // older doctor wrote. They fire on every tool call and block the session.
+    //
+    // There is deliberately NO auto-fix for an orphan script. Registering it with
+    // no matcher is exactly what created the stray entries; the right event and
+    // matcher can only be chosen by a person (hook-registry.json).
+    if (checkId.endsWith(".stray-gate-registration") && result.status === "FAIL" && target) {
         return {
             autoFixable: true,
-            fixClass: "register-hook",
+            fixClass: "remove-stray-gate-entries",
             fixTarget: target,
-            action: `Re-register ${target} in .claude/settings.json.`,
-            command: remediation ?? `Register ${target} in .claude/settings.json.`,
+            action: `Remove the matcher-less hook-gate.sh registrations from ${target}.`,
+            command: remediation ?? `Remove the matcher-less hook-gate.sh entries from ${target}.`,
         };
     }
     // refresh-sync — a company journal that is stale or never-synced. Only

package/dist/lib/doctor/registry.js

@@ -147,6 +147,7 @@ function runClaudeSettingsCheck(context) {
         ];
     }
     const count = countHookRegistrations(parsed);
+    const missingRequiredEvents = missingRequiredCommandHookEvents(parsed);
     return [
         {
             status: "PASS",
@@ -154,6 +155,17 @@ function runClaudeSettingsCheck(context) {
             target: settingsPath,
             message: `.claude/settings.json is present and valid (${count} hook registration${count === 1 ? "" : "s"}).`,
         },
+        {
+            status: missingRequiredEvents.length === 0 ? "PASS" : "FAIL",
+            checkId: "hooks.settings-required-command-hooks",
+            target: settingsPath,
+            message: missingRequiredEvents.length === 0
+                ? ".claude/settings.json registers command hooks for SessionStart and PreToolUse."
+                : `.claude/settings.json has no command hook for ${missingRequiredEvents.join(" or ")}.`,
+            remediation: missingRequiredEvents.length === 0
+                ? undefined
+                : "Restore the canonical hook registrations, e.g. `hq rescue -y --paths .claude`.",
+        },
         // US-004+: the settings file is present and valid, so the full Claude wiring
         // checks (script existence and executability, orphaned scripts, three-profile
         // membership, unquoted $CLAUDE_PROJECT_DIR, and core/hooks/<Event>/ executable
@@ -184,6 +196,37 @@ function countHookRegistrations(settings) {
     }
     return count;
 }
+/** The lifecycle events whose command hooks make the settings file operational. */
+const REQUIRED_COMMAND_HOOK_EVENTS = ["SessionStart", "PreToolUse"];
+/**
+ * Return each required lifecycle event that has no command hook with a non-empty
+ * command string. This deliberately mirrors check-hq-hooks.sh's jq predicate.
+ */
+function missingRequiredCommandHookEvents(settings) {
+    return REQUIRED_COMMAND_HOOK_EVENTS.filter((event) => !hasCommandHook(settings, event));
+}
+function hasCommandHook(settings, event) {
+    if (!settings || typeof settings !== "object")
+        return false;
+    const hooks = settings.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return false;
+    const eventEntries = hooks[event];
+    if (!Array.isArray(eventEntries))
+        return false;
+    return eventEntries.some((entry) => {
+        if (!entry || typeof entry !== "object")
+            return false;
+        const commandHooks = entry.hooks;
+        if (!Array.isArray(commandHooks))
+            return false;
+        return commandHooks.some((hook) => !!hook &&
+            typeof hook === "object" &&
+            hook.type === "command" &&
+            typeof hook.command === "string" &&
+            hook.command.length > 0);
+    });
+}
 /**
  * Build a registry pre-loaded with the default families. Hooks is the first
  * family; later families are registered here as they are implemented, each

package/dist/lib/doctor/stray-gate-entries.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Stray gate registrations written by an old `hq doctor --fix`.
+ *
+ * hq-cli v5.99.0 through v5.118.x "re-registered" every hook script that no
+ * settings command named. Since HQ moved to a single master-hook.sh entry that
+ * dispatches from .claude/hooks/hook-registry.json, EVERY script looked
+ * unregistered, so doctor appended one PreToolUse entry per script with no
+ * matcher:
+ *
+ *   { "hooks": [{ "type": "command", "timeout": 5,
+ *       "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/hook-gate.sh\" <id> \"$CLAUDE_PROJECT_DIR/.claude/hooks/<id>.sh\"" }] }
+ *
+ * With no matcher Claude Code runs each of them on every tool call, so guards
+ * such as block-hq-glob and protect-core block Bash, Skill and Read. An HQ
+ * update later moves them from settings.json into settings.local.json as
+ * "user customizations", where the release reset no longer clears them.
+ *
+ * Detection is deliberately exact: only an entry with no matcher, exactly one
+ * hook, timeout 5, and the doctor-generated command for a matching id counts.
+ * A hand-written hook is never touched.
+ */
+export declare function isStrayGateEntry(entry: unknown): boolean;
+/** Count stray entries across every hook event in a parsed settings object. */
+export declare function countStrayGateEntries(settings: unknown): number;
+/**
+ * Return a copy of `settings` with every stray entry removed. An event array
+ * left empty is dropped, and an empty `hooks` map is dropped, so a file whose
+ * only hooks were strays goes back to its original shape. Everything else,
+ * including permissions and real hooks, is preserved.
+ */
+export declare function removeStrayGateEntries(settings: unknown): {
+    settings: unknown;
+    removed: number;
+};
+//# sourceMappingURL=stray-gate-entries.d.ts.map

package/dist/lib/doctor/stray-gate-entries.js

@@ -0,0 +1,83 @@
+/**
+ * Stray gate registrations written by an old `hq doctor --fix`.
+ *
+ * hq-cli v5.99.0 through v5.118.x "re-registered" every hook script that no
+ * settings command named. Since HQ moved to a single master-hook.sh entry that
+ * dispatches from .claude/hooks/hook-registry.json, EVERY script looked
+ * unregistered, so doctor appended one PreToolUse entry per script with no
+ * matcher:
+ *
+ *   { "hooks": [{ "type": "command", "timeout": 5,
+ *       "command": "bash \"$CLAUDE_PROJECT_DIR/.claude/hooks/hook-gate.sh\" <id> \"$CLAUDE_PROJECT_DIR/.claude/hooks/<id>.sh\"" }] }
+ *
+ * With no matcher Claude Code runs each of them on every tool call, so guards
+ * such as block-hq-glob and protect-core block Bash, Skill and Read. An HQ
+ * update later moves them from settings.json into settings.local.json as
+ * "user customizations", where the release reset no longer clears them.
+ *
+ * Detection is deliberately exact: only an entry with no matcher, exactly one
+ * hook, timeout 5, and the doctor-generated command for a matching id counts.
+ * A hand-written hook is never touched.
+ */
+const GENERATED_COMMAND = /^bash "\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/hook-gate\.sh" ([A-Za-z0-9._-]+) "\$CLAUDE_PROJECT_DIR\/\.claude\/hooks\/([A-Za-z0-9._-]+)\.sh"$/;
+export function isStrayGateEntry(entry) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry))
+        return false;
+    const e = entry;
+    if (e.matcher !== undefined)
+        return false;
+    const keys = Object.keys(e);
+    if (keys.length !== 1 || keys[0] !== "hooks")
+        return false;
+    if (!Array.isArray(e.hooks) || e.hooks.length !== 1)
+        return false;
+    const hook = e.hooks[0];
+    if (!hook || hook.type !== "command" || hook.timeout !== 5 || typeof hook.command !== "string")
+        return false;
+    const m = GENERATED_COMMAND.exec(hook.command);
+    return !!m && m[1] === m[2];
+}
+/** Count stray entries across every hook event in a parsed settings object. */
+export function countStrayGateEntries(settings) {
+    const hooks = settings?.hooks;
+    if (!hooks || typeof hooks !== "object")
+        return 0;
+    let n = 0;
+    for (const entries of Object.values(hooks)) {
+        if (Array.isArray(entries))
+            n += entries.filter(isStrayGateEntry).length;
+    }
+    return n;
+}
+/**
+ * Return a copy of `settings` with every stray entry removed. An event array
+ * left empty is dropped, and an empty `hooks` map is dropped, so a file whose
+ * only hooks were strays goes back to its original shape. Everything else,
+ * including permissions and real hooks, is preserved.
+ */
+export function removeStrayGateEntries(settings) {
+    if (!settings || typeof settings !== "object" || Array.isArray(settings))
+        return { settings, removed: 0 };
+    const root = { ...settings };
+    const hooks = root.hooks;
+    if (!hooks || typeof hooks !== "object" || Array.isArray(hooks))
+        return { settings, removed: 0 };
+    let removed = 0;
+    const next = {};
+    for (const [event, entries] of Object.entries(hooks)) {
+        if (!Array.isArray(entries)) {
+            next[event] = entries;
+            continue;
+        }
+        const kept = entries.filter((e) => !isStrayGateEntry(e));
+        removed += entries.length - kept.length;
+        if (kept.length > 0 || entries.length === 0)
+            next[event] = kept;
+    }
+    if (Object.keys(next).length > 0)
+        root.hooks = next;
+    else
+        delete root.hooks;
+    return { settings: root, removed };
+}
+//# sourceMappingURL=stray-gate-entries.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@indigoai-us/hq-cli",
-  "version": "5.117.2",
+  "version": "5.117.3",
   "description": "HQ by Indigo management CLI \u2014 modules and cloud sync",
   "main": "dist/index.js",
   "bin": {