@indigoai-us/hq-cli 5.115.4 → 5.115.5

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 ## [Unreleased]
 
+## [5.115.5] — 2026-09-15
+
+### Fixed
+
+- The setting that turns the end-of-turn checkpoint requirement off,
+  `HQ_CHECKPOINT_GATE`, now works from `.claude/settings.json` on every runtime.
+  Before, only Claude Code passed that setting through to the checkpoint hook,
+  so if you work in Codex or Grok, writing it in the settings file did nothing
+  and there was no sign of why. hq now reads the file itself. As with the other
+  checkpoint settings, `settings.local.json` overrides it, anything you set in
+  your terminal overrides both, and `false` or `0` written as plain JSON works
+  as well as `"0"`. If the value is something the setting does not understand,
+  hq names it and leaves the requirement on rather than guessing.
+
 ## [5.115.4] — 2026-09-15
 
 ### Changed

package/assets/scaffold/core/scripts/checkpoint-stop-gate.sh

@@ -5,6 +5,12 @@
 
 set -uo pipefail
 
+# The main block ends with `} 2>/dev/null`: a Stop hook must not spray
+# diagnostics into a session. Keep one copy of the real stderr so a
+# misconfigured operator switch — the one failure the operator alone can fix,
+# and otherwise invisible — still has somewhere to be said.
+exec 3>&2
+
 {
   self_hq="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"
   HQ="${CLAUDE_PROJECT_DIR:-${HQ_ROOT:-$self_hq}}"
@@ -49,6 +55,88 @@ set -uo pipefail
     return 0
   }
 
+  # checkpoint_gate_trim — strips only the edges. Deleting interior whitespace
+  # would quietly repair a typo: "f alse" would become a valid `false` and
+  # disable the gate the operator was trying to keep on.
+  checkpoint_gate_trim() {
+    local s="$1"
+    s="${s#"${s%%[![:space:]]*}"}"
+    s="${s%"${s##*[![:space:]]}"}"
+    printf '%s' "$s"
+  }
+
+  # checkpoint_gate_setting — one operator switch, resolved the way hq-cli
+  # resolves it: the process environment first, then the HQ root's
+  # `.claude/settings.json` `env` block (overlaid by `settings.local.json`, the
+  # order Claude Code merges them).
+  #
+  # Reading the file matters because only Claude Code exports that block into
+  # hook processes. Under Codex or grok the variable is never set, so an
+  # operator who wrote the switch into settings.json would have had it silently
+  # ignored on exactly the runtimes where they cannot see why. Fail-open: any
+  # missing file, absent jq, or unreadable value leaves the gate at its default.
+  #
+  # Prints the raw value and returns 0 when one resolves. Returns 1 when the
+  # highest-priority file that mentions the key holds something unreadable — a
+  # present key stops the lookup rather than falling through, so a stale `"0"`
+  # further down cannot be promoted by a typo in the file above it. Same
+  # precedence the TypeScript resolver uses.
+  checkpoint_gate_setting() {
+    local key="$1" value="" file raw
+    eval "value=\${$key:-}"
+    value="$(checkpoint_gate_trim "$value")"
+    if [ -n "$value" ]; then
+      printf '%s' "$value"
+      return 0
+    fi
+    command -v jq >/dev/null 2>&1 || return 0
+    for file in "$HQ/.claude/settings.local.json" "$HQ/.claude/settings.json"; do
+      [ -r "$file" ] || continue
+      # Strings, and JSON's own true/false/0/1 — the literal an operator reaches
+      # for first — all resolve; null, an object, or an array does not. The
+      # leading marker separates "absent" (no output) from "present but
+      # unreadable" (`-`), which a bare value could not encode.
+      raw="$(jq -r --arg k "$key" '
+        try (
+          if (.env | type) == "object" and (.env | has($k))
+          then (.env[$k]
+                | if type == "string" or type == "boolean" or type == "number"
+                  then "+" + tostring
+                  else "-" end)
+          else empty end
+        ) catch empty' "$file" 2>/dev/null || true)"
+      case "$raw" in
+        "") continue ;;
+        -*) ;;
+        +*)
+          value="$(checkpoint_gate_trim "${raw#+}")"
+          if [ -n "$value" ]; then
+            printf '%s' "$value"
+            return 0
+          fi
+          ;;
+      esac
+      printf 'checkpoint-stop-gate: ignoring %s in %s (not a value it can read; expected a string such as "0" or "1")\n' \
+        "$key" "$file" >&3 2>/dev/null
+      return 1
+    done
+    return 0
+  }
+
+  # Normalizes one switch to 0, 1, or empty (= not set). An unreadable value is
+  # named on stderr rather than passed over: the operator asked for something.
+  checkpoint_gate_switch() {
+    local key="$1" raw
+    raw="$(checkpoint_gate_setting "$key" 2>/dev/null)" || return 0
+    [ -n "$raw" ] || return 0
+    case "$(printf '%s' "$raw" | tr '[:upper:]' '[:lower:]')" in
+      0|false|off|no) printf '0' ;;
+      1|true|on|yes) printf '1' ;;
+      *) printf 'checkpoint-stop-gate: ignoring %s=%s (expected 0/1, false/true, off/on or no/yes)\n' "$key" "$raw" >&3 2>/dev/null ;;
+    esac
+    return 0
+  }
+
   input="$(cat 2>/dev/null || printf '{}')"
   input_fields="$(printf '%s' "$input" | jq -r '[.transcript_path // "", .session_id // ""] | @tsv' 2>/dev/null)" || exit 0
   IFS=$'\t' read -r transcript_path session_id <<<"$input_fields" || exit 0
@@ -57,6 +145,15 @@ set -uo pipefail
   # recursively demand another checkpoint of itself.
   [ "${HQ_CHECKPOINT_SIBLING:-}" = "1" ] && exit 0
 
+  # Resolved once: every branch below reads this instead of the raw variable.
+  gate_switch="$(checkpoint_gate_switch HQ_CHECKPOINT_GATE)"
+  # That was the only diagnostic, so drop the duplicate before anything is
+  # spawned. The detached `nohup ... &` commands below redirect fds 1 and 2
+  # only: a surviving fd 3 would be inherited by them and hold the hook
+  # runner's stderr pipe open, so a runner that reads stderr to EOF would wait
+  # on the supposedly detached checkpoint instead of on this shell.
+  exec 3>&-
+
   # Company-scope gate ---------------------------------------------------------
   # An OPT-IN requirement layered onto this Stop hook: for an operator whose
   # email domain is listed in HQ_CHECKPOINT_SCOPE_GATE_DOMAINS (comma-separated,
@@ -69,7 +166,7 @@ set -uo pipefail
   # alongside the checkpoint gate. Binding is a single recoverable call, so the
   # block loops only until the operator declares a scope.
   gate_domains="${HQ_CHECKPOINT_SCOPE_GATE_DOMAINS:-}"
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) ;;
     *)
       gate_session_id="$(printf '%s' "$input" | jq -r '.session_id // ""' 2>/dev/null || true)"
@@ -120,7 +217,7 @@ set -uo pipefail
             *) [ -d "$gate_root/companies/$bound_co" ] && gate_bound=1 ;;
           esac
           if [ "$gate_bound" = 0 ]; then
-            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
+            company_reason="$(printf 'This session has not declared its scope, and a scope is required before the turn can end. Decide where this work belongs, then bind the session and finish the turn with your user-facing reply as the final text after the command output:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug <company-slug>\n\nUse a real tenant slug from companies/manifest.yaml — the company this session is actually working in, never an invented one. If this session does no company-scoped work, bind it to the reserved personal scope instead:\n\n  bash %s/core/scripts/hq-session.sh --session-id %s set company_slug personal\n\nAn operator can also disable this requirement for the run by exporting HQ_CHECKPOINT_GATE=0, or for every runtime by putting \"env\": {\"HQ_CHECKPOINT_GATE\": \"0\"} in .claude/settings.json.' "$gate_root" "$gate_session_id" "$gate_root" "$gate_session_id")"
             printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$company_reason" | hq_json_encode)"
             exit 0
           fi
@@ -133,7 +230,7 @@ set -uo pipefail
 
   # Operator switches precede runtime and identity eligibility. A forced gate
   # intentionally bypasses the rollout rules for local trials and tests.
-  case "${HQ_CHECKPOINT_GATE:-}" in
+  case "$gate_switch" in
     0) exit 0 ;;
     1) enforce=true ;;
     *)
@@ -151,7 +248,7 @@ set -uo pipefail
 
   refresh_eligibility() {
     command -v hq >/dev/null 2>&1 || return 0
-    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 &)
+    (nohup env HQ_CHECKPOINT_RUNTIME="$runtime" hq core checkpoint --gate-probe >/dev/null 2>&1 3>&- &)
   }
 
   if [ "$runtime" = "codex" ] && [ "$enforce" = false ]; then
@@ -511,7 +608,7 @@ set -uo pipefail
        --trigger stop-gate-auto \
        --transcript "$transcript_path" \
        --summary "turn ended with its user-facing reply already delivered" \
-       >/dev/null 2>&1 &)
+       >/dev/null 2>&1 3>&- &)
     rm -f "$block_count_file" 2>/dev/null || true
     exit 0
   fi

package/dist/commands/core-checkpoint.js

@@ -49,6 +49,12 @@ const GROK_SIBLING_MAX_TURNS = "100";
  * hosts never read it.
  */
 const SIBLING_SETTING = "HQ_CHECKPOINT_AGENT";
+/**
+ * The Stop gate's own switch. Resolved through the same settings file as the
+ * sibling switch so it reaches Codex and grok, whose hosts never export the
+ * `.claude/settings.json` `env` block into a hook process.
+ */
+const GATE_SETTING = "HQ_CHECKPOINT_GATE";
 const SIBLING_SETTING_OFF = new Set(["0", "false", "off", "no"]);
 const SIBLING_SETTING_ON = new Set(["1", "true", "on", "yes"]);
 const FALLBACK_BACKEND_ORDER = ["claude", "codex", "grok"];
@@ -445,12 +451,13 @@ function checkpointGateRuntime() {
         return runtime;
     return "other";
 }
-function gateEligibility(runtime) {
-    const forced = process.env.HQ_CHECKPOINT_GATE;
-    if (forced === "0")
-        return false;
-    if (forced === "1")
-        return true;
+function gateEligibility(runtime, liveRoot) {
+    // An operator switch precedes runtime and identity eligibility, and is read
+    // from the settings file as well as the environment: under Codex and grok the
+    // environment is the one place the operator cannot reach.
+    const forced = resolveSwitchSetting(liveRoot, GATE_SETTING);
+    if (forced !== undefined)
+        return forced;
     if (runtime === "claude")
         return true;
     if (runtime !== "codex")
@@ -472,7 +479,7 @@ function writeGateVerdict(liveRoot) {
     const stateDir = path.join(liveRoot, "workspace", "orchestrator", "hook-state");
     fs.mkdirSync(stateDir, { recursive: true });
     const runtime = checkpointGateRuntime();
-    const eligible = gateEligibility(runtime);
+    const eligible = gateEligibility(runtime, liveRoot);
     fs.writeFileSync(path.join(stateDir, `checkpoint-gate-eligible-${runtime}`), eligible ? "1" : "0");
     printResult(eligible ? "eligible" : "ineligible");
 }
@@ -637,36 +644,45 @@ function settingsEnvValue(liveRoot, key) {
     return { kind: "absent" };
 }
 /** Maps one resolved value onto the switch, reporting a vocabulary it cannot read. */
-function parseSiblingSetting(raw, source) {
+function parseSwitchSetting(key, raw, source) {
     const value = raw.toLowerCase();
     if (SIBLING_SETTING_OFF.has(value))
         return false;
     if (SIBLING_SETTING_ON.has(value))
         return true;
-    printError(`checkpoint: ignoring ${SIBLING_SETTING}=${raw} from ${source} ` +
+    printError(`checkpoint: ignoring ${key}=${raw} from ${source} ` +
         "(expected 0/1, false/true, off/on or no/yes)");
-    return true;
+    return undefined;
 }
 /**
- * Whether the maintenance sibling may run at all. The process environment wins
- * over the settings file, so a one-off `HQ_CHECKPOINT_AGENT=0 hq core
- * checkpoint …` still works and a host that exports the settings `env` block
- * (Claude Code does) agrees with a host that does not.
+ * One operator switch: the process environment first, then the HQ root's
+ * Claude settings. `undefined` means nobody set it — distinct from a setting
+ * that says "off", and distinct from one this cannot read (reported, then
+ * treated as unset so a typo never silently flips a default).
  */
-export function siblingEnabledBySetting(liveRoot) {
-    const fromEnv = process.env[SIBLING_SETTING]?.trim();
+function resolveSwitchSetting(liveRoot, key) {
+    const fromEnv = process.env[key]?.trim();
     if (fromEnv)
-        return parseSiblingSetting(fromEnv, "the environment");
-    const lookup = settingsEnvValue(liveRoot, SIBLING_SETTING);
+        return parseSwitchSetting(key, fromEnv, "the environment");
+    const lookup = settingsEnvValue(liveRoot, key);
     if (lookup.kind === "absent")
-        return true;
+        return undefined;
     if (lookup.kind === "invalid") {
-        printError(`checkpoint: ignoring ${SIBLING_SETTING} in ${lookup.source}: ` +
+        printError(`checkpoint: ignoring ${key} in ${lookup.source}: ` +
             `${JSON.stringify(lookup.raw) ?? String(lookup.raw)} is not a value it can read ` +
             '(expected a string such as "0" or "1")');
-        return true;
+        return undefined;
     }
-    return parseSiblingSetting(lookup.value, lookup.source);
+    return parseSwitchSetting(key, lookup.value, lookup.source);
+}
+/**
+ * Whether the maintenance sibling may run at all. The process environment wins
+ * over the settings file, so a one-off `HQ_CHECKPOINT_AGENT=0 hq core
+ * checkpoint …` still works and a host that exports the settings `env` block
+ * (Claude Code does) agrees with a host that does not.
+ */
+export function siblingEnabledBySetting(liveRoot) {
+    return resolveSwitchSetting(liveRoot, SIBLING_SETTING) ?? true;
 }
 /** Rejects an unknown `--backend` without paying for the probe that resolves one. */
 function assertKnownBackend(requested) {

package/package.json

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