@indigoai-us/hq-cli 5.103.12 → 5.103.13

package/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 ## [Unreleased]
 
+## [5.103.13] — 2026-08-20
+
+### Fixed
+
+- The bundled checkpoint stop-gate now *enforces* the user-facing reply
+  instead of only asking for it: a satisfying checkpoint on a work turn whose
+  genuine reply is under `HQ_CHECKPOINT_REPLY_MIN` non-whitespace characters
+  (default 80) blocks once with a dedicated reply demand, stamped per
+  checkpoint tool id and counted against the shared 3-consecutive-blocks loop
+  guard, so it can never strand a session. The reply window accepts text on
+  either side of the checkpoint and crosses the gate's own block feedback, so
+  an agent that already replied is never told to repeat itself — composing
+  with the reply-aware block variants — while mid-turn notes written before
+  the last work tool do not count. Flag exemptions are parsed robustly:
+  `--gate-probe` / `--idle` inside a quoted `--summary` value are data, not
+  flags, and a compound command ending in a checkpoint keeps owing the reply.
+  The `--idle` path of `hq core checkpoint` prints a conditional reminder
+  matching the gate's idle-only exemption.
+
 ## [5.103.12] — 2026-08-20
 
 ## [5.103.11] — 2026-08-20

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

@@ -232,65 +232,105 @@ set -uo pipefail
       end;
     def checkpoint_command:
       test("(^|[;&|(\\s])(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint(\\s|$)");
+    def strip_quoted:
+      # Remove quoted spans so flag text inside a --summary value (e.g.
+      # --summary "investigated --gate-probe behavior") is never mistaken for
+      # an active flag. Double-quoted spans honor backslash escapes. The
+      # u0027 escape is a single-quote character, written that way because
+      # this whole program lives inside a single-quoted shell string.
+      gsub("\"(\\\\.|[^\"\\\\])*\""; "")
+      | gsub("\u0027[^\u0027]*\u0027"; "");
+    def checkpoint_flag($flag):
+      strip_quoted | test("(^|\\s)" + $flag + "(\\s|$)");
+    def pure_checkpoint:
+      # The command is ONLY a checkpoint invocation (optional env-assignment
+      # prefix, no other command joined by a separator). A compound call like
+      # `git status; hq core checkpoint --idle` did other work in the same
+      # tool call, so its exemptions must not apply.
+      strip_quoted
+      | test("^\\s*(command\\s+)?([A-Za-z_][A-Za-z0-9_]*=[^\\s]*\\s+)*hq\\s+core\\s+checkpoint([\\s][^;&|\n]*)?$");
+    def gate_feedback_user:
+      # This gate surfaces its own Stop feedback as a synthetic user row. That
+      # row is a turn boundary for the checkpoint requirement, but NOT for
+      # deciding whether the USER has been answered: a reply the agent wrote
+      # before the block is already on screen and must never be demanded again
+      # (double-messaging).
+      .type == "user"
+      and ((.message.content? | type) == "string")
+      and (.message.content | startswith("Stop hook feedback:"));
     [split("\n")[] | select(length > 0) | {line: ., entry: (fromjson)}] as $rows
     | [range(0; $rows | length) | select($rows[.].entry | real_user)] as $user_indexes
     | if ($user_indexes | length) == 0 then error("no real user entry") else
         $user_indexes[-1] as $user_index
-        | $rows[($user_index + 1):] as $turn
+        | ([$user_indexes[] | select(($rows[.].entry | gate_feedback_user) | not)]
+           | if length > 0 then .[-1] else $user_indexes[0] end) as $genuine_index
         | [
-            range(0; $turn | length) as $ti
-            | $turn[$ti].entry
+            range($genuine_index + 1; $rows | length) as $ri
+            | $rows[$ri].entry
             | if .type == "assistant" then
                 .message.content?
                 | if type == "array" then .[]? else empty end
-                | select(.type == "tool_use")
-                | {
-                    i: $ti,
-                    runtime: "claude",
-                    id: (.id? // ""),
-                    name: (.name? // ""),
-                    command: (.input.command? // "")
-                  }
+                | if .type == "tool_use" then
+                    {
+                      row: $ri,
+                      kind: "tool",
+                      runtime: "claude",
+                      id: (.id? // ""),
+                      name: (.name? // ""),
+                      command: (.input.command? // "")
+                    }
+                  elif .type == "text" then
+                    # Whitespace-stripped so blank filler can never pass for a
+                    # reply.
+                    {row: $ri, kind: "text",
+                     chars: ((.text? // "") | gsub("\\s+"; "") | length)}
+                  else empty
+                  end
               elif (
                 .type == "response_item"
                 and (.payload.type? == "custom_tool_call" or .payload.type? == "function_call")
               ) then
                 .payload
                 | {
-                    i: $ti,
+                    row: $ri,
+                    kind: "tool",
                     runtime: "codex",
                     id: (.call_id? // .id? // ""),
                     name: (.name? // ""),
                     command: codex_command
                   }
+              elif (
+                .type == "response_item"
+                and .payload.type? == "message"
+                and .payload.role? == "assistant"
+                and ((.payload.content? | type) == "array")
+              ) then
+                {row: $ri, kind: "text",
+                 chars: ([.payload.content[]? | (.text? // "")] | join("")
+                         | gsub("\\s+"; "") | length)}
               else empty
               end
-          ] as $tools
+          ] as $events
+        | [$events[] | select(.row > $user_index)] as $seg_events
+        | [$seg_events[] | select(.kind == "tool")] as $tools
         | (if ($tools | length) > 0 then $tools[-1] else {} end) as $last_tool
-        # A user-visible assistant reply strictly AFTER the turn-s last tool call
-        # means the user has already been answered, so the block reason must
-        # forbid a restatement instead of demanding one. Text earlier in the turn
-        # (status notes between tool calls) does not count as the reply.
-        | (if ($tools | length) > 0 then $tools[-1].i else -1 end) as $last_tool_i
-        | ([
-             $turn[($last_tool_i + 1):][]
-             | .entry
-             | if .type == "assistant" then
-                 .message.content?
-                 | if type == "string" then .
-                   elif type == "array" then ([.[]? | select(.type == "text") | (.text? // "")] | join(""))
-                   else ""
-                   end
-               elif (
-                 .type == "response_item"
-                 and .payload.type? == "message"
-                 and .payload.role? == "assistant"
-                 and ((.payload.content? | type) == "array")
-               ) then
-                 ([.payload.content[]? | (.text? // "")] | join(""))
-               else ""
-               end
-           ] | join("") | test("\\S")) as $replied
+        # Reply visible after THIS segment last tool call: chooses which block
+        # variant an unsatisfied turn gets (write your reply vs do not repeat
+        # it). Mid-turn notes between tool calls do not count.
+        | ([range(0; $seg_events | length) | select($seg_events[.].kind == "tool")]
+           | if length > 0 then .[-1] else -1 end) as $seg_last_tool_index
+        | ([$seg_events[($seg_last_tool_index + 1):][] | select(.kind == "text") | .chars]
+           | add // 0) as $seg_reply_chars
+        # Reply owed by the WHOLE genuine turn: all assistant text after its
+        # last non-checkpoint tool call, crossing this gate feedback
+        # boundaries. An agent that replied and then checkpointed (in either
+        # order across a block) is never told to write the reply again.
+        | ([range(0; $events | length)
+            | select(($events[.].kind == "tool")
+                     and (($events[.].command | checkpoint_command) | not))]
+           | if length > 0 then .[-1] else -1 end) as $last_work_index
+        | ([$events[($last_work_index + 1):][] | select(.kind == "text") | .chars]
+           | add // 0) as $reply_chars
         | ([$tools[] | select((.command | checkpoint_command) | not)] | length) as $work_tool_count
         | ([
              $rows[]
@@ -305,18 +345,50 @@ set -uo pipefail
             ($tools | length) > 0
             and ($last_tool.command | checkpoint_command)
           ) then
-            if $last_tool.runtime == "claude" and ($last_result_error | not) then "1"
+            if $last_tool.runtime == "claude" and ($last_result_error | not) then
+              # A reply is owed after a real (--summary) checkpoint always, and
+              # after an --idle checkpoint only when the turn ran other tools
+              # (a read-only investigation still owes its findings). A
+              # --gate-probe is pure bookkeeping and never owes one. Both
+              # exemptions apply only to a PURE checkpoint invocation, with the
+              # flags read outside quoted text — a compound command did other
+              # work in the same call, and flag text inside a --summary value
+              # is data, not a flag.
+              (
+                (($last_tool.command | pure_checkpoint) | not)
+                or (
+                  (($last_tool.command | checkpoint_flag("--gate-probe")) | not)
+                  and (
+                    (($last_tool.command | checkpoint_flag("--idle")) | not)
+                    or ($work_tool_count > 0)
+                  )
+                )
+              ) as $reply_required
+              | "1\t\($last_tool.id)\t\($reply_chars)\t\(if $reply_required then 1 else 0 end)"
             elif $last_tool.runtime == "codex" then "stamp"
-            else (if $replied then "0-replied" else "0-unreplied" end)
+            else (if $seg_reply_chars > 0 then "0-replied" else "0-unreplied" end)
             end
           elif $work_tool_count == 0 then "idle"
-          else (if $replied then "0-replied" else "0-unreplied" end)
+          else (if $seg_reply_chars > 0 then "0-replied" else "0-unreplied" end)
           end
       end
   ' 2>/dev/null)" || exit 0
+  # A Claude success verdict carries the satisfying checkpoint's tool id, the
+  # count of non-whitespace assistant text characters delivered after the
+  # genuine turn's last work tool (its user-facing reply, wherever it sits
+  # relative to the checkpoint), and whether this checkpoint shape owes the
+  # user a reply at all. An unsatisfied verdict says whether a reply is
+  # already visible, so the block message never demands a duplicate.
   satisfied="$parsed"
   replied=0
-  case "$satisfied" in
+  reply_tool_id=""
+  reply_chars=""
+  reply_required=""
+  gate_tab="$(printf '\t')"
+  case "$parsed" in
+    "1${gate_tab}"*)
+      IFS="$gate_tab" read -r satisfied reply_tool_id reply_chars reply_required <<<"$parsed"
+      ;;
     0-replied) satisfied=0; replied=1 ;;
     0-unreplied) satisfied=0 ;;
   esac
@@ -350,49 +422,95 @@ set -uo pipefail
   # there is nothing to record. Demanding one anyway turns every conversational
   # reply — and every background-notification wake-up — into an --idle round
   # trip that writes no state and only costs a turn.
+  # Consecutive-block counter, shared by every block this gate can emit (the
+  # missing-checkpoint demand and the reply demand alike). A session whose
+  # checkpoint command keeps FAILING (a broken or mid-self-update `hq` binary)
+  # would otherwise be re-prompted on every Stop, forever. Past the cap the
+  # gate fails open per this file's never-strand-a-session doctrine; any Stop
+  # that ends in an allow resets it.
+  block_count_file="$state_dir/checkpoint-block-count-$session_key"
+  block_count="$(tr -d '\r\n' <"$block_count_file" 2>/dev/null || true)"
+  case "$block_count" in
+    ''|*[!0-9]*) block_count=0 ;;
+  esac
+  bump_block_count() {
+    block_count_tmp="$block_count_file.$$"
+    if (umask 077 && printf '%s' "$((block_count + 1))" >"$block_count_tmp" && mv -f "$block_count_tmp" "$block_count_file"); then
+      :
+    else
+      rm -f "$block_count_tmp" 2>/dev/null || true
+    fi
+  }
+
   if [ "$satisfied" = "1" ] || [ "$satisfied" = "idle" ]; then
     if [ "$runtime" = "codex" ]; then
       rm -f "$state_dir/codex-checkpoint-reprompt-$session_key" 2>/dev/null || true
     fi
-    rm -f "$state_dir/checkpoint-block-count-$session_key" 2>/dev/null || true
+
+    # Reply-owed enforcement (Claude runtime only). The checkpoint payload
+    # goes to the background sibling, never the user. A genuine turn that did
+    # work and reaches a satisfying checkpoint with (next to) no assistant
+    # text after its last WORK tool call is a turn whose user-facing reply is
+    # missing, however rich the checkpoint flags are: block once and demand
+    # the reply. The window deliberately crosses this gate's own feedback
+    # boundaries and accepts a reply on either side of the checkpoint, so an
+    # agent that replied and then checkpointed is never told to repeat itself
+    # (double-messaging is the failure the reply-aware block variants exist
+    # to prevent). Evidence (transcript audit 2026-08-19, 1471 stop-gate
+    # checkpoint turns): 2.7% ended with no reply anywhere while the substance
+    # lived only in the checkpoint payload. The nudge fires at most once per
+    # checkpoint tool id (stamped in hook-state), so a legitimately terse turn
+    # costs exactly one extra Stop round-trip and the gate can never loop.
+    # Codex is excluded: its Stop feedback is a synthetic re-prompt with its
+    # own delivery contract. HQ_CHECKPOINT_REPLY_MIN overrides the minimum
+    # non-whitespace character threshold; 0 disables the enforcement.
+    if [ "$satisfied" = "1" ] && [ "$runtime" = "claude" ] \
+      && [ "$reply_required" = "1" ] && [ -n "$reply_tool_id" ]; then
+      reply_min="${HQ_CHECKPOINT_REPLY_MIN:-80}"
+      case "$reply_min" in ''|*[!0-9]*) reply_min=80 ;; esac
+      case "$reply_chars" in ''|*[!0-9]*) reply_chars=0 ;; esac
+      if [ "$reply_min" -gt 0 ] && [ "$reply_chars" -lt "$reply_min" ] && [ "$block_count" -lt 3 ]; then
+        nudge_file="$state_dir/checkpoint-reply-nudge-$session_key"
+        nudge_prev="$(cat "$nudge_file" 2>/dev/null || true)"
+        if [ "$nudge_prev" != "$reply_tool_id" ]; then
+          nudge_tmp="$nudge_file.$$"
+          if (umask 077 && printf '%s' "$reply_tool_id" >"$nudge_tmp" && mv -f "$nudge_tmp" "$nudge_file"); then
+            bump_block_count
+            reply_reason='Checkpoint recorded — but the turn cannot end yet: the user has not received a reply this turn. The checkpoint payload went to a background maintenance agent; the user sees NONE of it, and nothing you have written since your last real action reads as a reply to them. Deliver your complete reply to the user now, as ordinary text: every result, finding, link, decision, and anything awaiting their input, in plain language. Do not run another checkpoint and do not call any other tool — end the turn with text only.'
+            printf '{"decision":"block","reason":%s}\n' "$(printf '%s' "$reply_reason" | hq_json_encode)"
+            exit 0
+          fi
+          rm -f "$nudge_tmp" 2>/dev/null || true
+        fi
+      fi
+    fi
+    # This Stop ends in an allow: the session is not stuck, so the
+    # consecutive-block counter starts over.
+    rm -f "$block_count_file" 2>/dev/null || true
     exit 0
   fi
 
-  # Loop guard: a session whose checkpoint command keeps FAILING (a broken or
-  # mid-self-update `hq` binary) would otherwise be re-prompted on every Stop,
-  # forever — block → retry checkpoint → error → block again. Cap consecutive
-  # blocks per session; past the cap, fail open per this file's
-  # never-strand-a-session doctrine. Any successful checkpoint or idle turn
-  # resets the counter above.
-  block_count_file="$state_dir/checkpoint-block-count-$session_key"
-  block_count="$(tr -d '\r\n' <"$block_count_file" 2>/dev/null || true)"
-  case "$block_count" in
-    ''|*[!0-9]*) block_count=0 ;;
-  esac
+  # Loop guard for the missing-checkpoint demand below: cap consecutive blocks
+  # per session, then fail open (see the counter's comment above).
   if [ "$block_count" -ge 3 ]; then
     exit 0
   fi
-  block_count_tmp="$block_count_file.$$"
-  if (umask 077 && printf '%s' "$((block_count + 1))" >"$block_count_tmp" && mv -f "$block_count_tmp" "$block_count_file"); then
-    :
-  else
-    rm -f "$block_count_tmp" 2>/dev/null || true
-  fi
+  bump_block_count
 
   # Built with printf rather than concatenation so the session id can appear in
   # both commands without re-splitting the message into fragments.
   #
   # Two variants, chosen from the transcript rather than left to the agent's
-  # judgment: the historical single instruction either demanded a full
-  # restatement (double-messaging hosts that render pre-tool text — the CLI and
-  # the desktop app both do) or forbade post-checkpoint text (hiding the reply
-  # when the agent had not yet written one). The transcript already tells us
-  # which case we are in, so say exactly one thing.
+  # judgment: a single instruction either demanded a full restatement
+  # (double-messaging hosts that render pre-tool text) or forbade
+  # post-checkpoint text (hiding the reply when the agent had not yet written
+  # one). The transcript already tells us which case we are in, so say exactly
+  # one thing.
   flags_spec='  hq core checkpoint --session-id %s --trigger stop-gate --summary "<what changed, in one line>" [--file <path>] [--decision "<choice and why>"] [--learning "<reusable rule>"] [--next "<outstanding step>"]\n\nOnly --summary is required, and the repeatable flags are what the sibling uses to enrich the record, distil policies and update the indexes — a bare summary gives it almost nothing to work with. Write them as machine record, not prose for the user, and pass each one that genuinely applies:\n  --file      every path you created or modified this turn\n  --decision  a choice you made that a reader would otherwise have to reverse-engineer\n  --learning  a rule that changes how someone acts next time, not a restatement of what just happened\n  --next      work that is genuinely still outstanding\nOmit a flag rather than padding it: an empty or invented learning is worse than none.\n\nIf this turn only read or inspected things and changed no state, the correct call instead is:\n\n  hq core checkpoint --session-id %s --idle'
   if [ "$replied" = 1 ]; then
     reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint before it can end.\n\nYour user-facing reply is ALREADY delivered — the message you just wrote is visible to the user. Do NOT send it again, in full or summarized: repeating it double-messages the user, which is exactly the bug this gate guards against.\n\nTHE SIBLING (a background maintenance agent) reads only the checkpoint payload, never your chat reply — anything it needs must go into the flags.\n\nRun the checkpoint now as the FINAL action of the turn and end the turn immediately after it, adding no further text:\n\n'"$flags_spec" "$session_id" "$session_id")"
   else
-    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message.\n\n'"$flags_spec" "$session_id" "$session_id")"
+    reason="$(printf 'This turn changed something, so it needs an end-of-turn checkpoint. Two different audiences are involved — do not conflate them:\n\n1. THE USER reads your normal chat reply. You have not sent one yet this turn — everything you owe them (results, links, answers, status, decisions) must go into it. The checkpoint is invisible to them and does NOT count as having replied.\n2. THE SIBLING (a background maintenance agent) reads the checkpoint payload. It never sees your chat reply, so anything it needs must go into the flags.\n\nORDER: run the checkpoint FIRST, then deliver your complete user-facing reply as the FINAL text of the turn — final-position text is the one placement every host renders in full. Every link, URL, instruction, command, and decision the user needs must appear in that final message. The gate enforces this: a turn that ends without a user-facing reply is blocked until the reply is delivered.\n\n'"$flags_spec" "$session_id" "$session_id")"
   fi
 
   # Codex surfaces a blocked Stop reason as a synthetic user prompt. Preserve

package/dist/commands/core-checkpoint.d.ts

@@ -20,12 +20,21 @@ type SpawnableBackend = Exclude<Backend, "none">;
  * (both the CLI and the desktop app render pre-tool-call text), while an
  * unconditional "no commentary after" hid the reply from agents that had not
  * yet written one. The Stop gate makes the same distinction from the
- * transcript; this line covers proactive checkpoints the gate never sees.
- * Mirrors the hq-core policies
+ * transcript — and backstops this reminder mechanically: a satisfying
+ * checkpoint on a work turn whose genuine reply is still missing is blocked
+ * once with a dedicated reply demand. This line covers proactive checkpoints
+ * the gate never sees. Mirrors the hq-core policies
  * `checkpoint-is-bookkeeping-not-user-communication` and
  * `checkpoint-is-not-the-user-report`.
  */
 export declare const CHECKPOINT_REPLY_REMINDER: string;
+/**
+ * The --idle variant: an idle-only turn (nothing ran, nothing to report) is
+ * exempt at the Stop gate, so this text must never order a reply into
+ * existence — but an --idle after read-only work is NOT exempt (the gate
+ * demands the findings), so the conditional half still points there.
+ */
+export declare const CHECKPOINT_IDLE_REPLY_REMINDER: string;
 /**
  * Kept in TypeScript rather than in a bundled asset: it is an instruction to
  * a locally-installed agent, not a scaffold script that should be packaged.

package/dist/commands/core-checkpoint.js

@@ -51,8 +51,10 @@ class CheckpointUsageError extends Error {
  * (both the CLI and the desktop app render pre-tool-call text), while an
  * unconditional "no commentary after" hid the reply from agents that had not
  * yet written one. The Stop gate makes the same distinction from the
- * transcript; this line covers proactive checkpoints the gate never sees.
- * Mirrors the hq-core policies
+ * transcript — and backstops this reminder mechanically: a satisfying
+ * checkpoint on a work turn whose genuine reply is still missing is blocked
+ * once with a dedicated reply demand. This line covers proactive checkpoints
+ * the gate never sees. Mirrors the hq-core policies
  * `checkpoint-is-bookkeeping-not-user-communication` and
  * `checkpoint-is-not-the-user-report`.
  */
@@ -62,6 +64,15 @@ export const CHECKPOINT_REPLY_REMINDER = "checkpoint: REMINDER — this checkpoi
     "the user, write your user-facing reply now as the FINAL text of the turn. If you " +
     "already delivered it earlier this turn, end the turn now WITHOUT repeating it — the " +
     "user has already seen that message, and repeating it double-messages them.";
+/**
+ * The --idle variant: an idle-only turn (nothing ran, nothing to report) is
+ * exempt at the Stop gate, so this text must never order a reply into
+ * existence — but an --idle after read-only work is NOT exempt (the gate
+ * demands the findings), so the conditional half still points there.
+ */
+export const CHECKPOINT_IDLE_REPLY_REMINDER = "checkpoint: idle recorded — invisible bookkeeping; the user sees none of it. If this " +
+    "turn surfaced findings or answers the user has not been told, deliver them now as the " +
+    "turn's final text. If the turn genuinely produced nothing to report, end it.";
 function printResult(line) {
     process.stdout.write(`${line}\n`);
 }
@@ -824,8 +835,10 @@ function runCheckpoint(options, command, group) {
         writeStamps(liveRoot, resolveSessionId(options, command, readPayload(options.payload)));
         printResult("checkpoint: idle (nothing to record)");
         // An idle turn persisted nothing, but a read-only turn can still have
-        // produced substantive findings the user has not been told about.
-        printResult(CHECKPOINT_REPLY_REMINDER);
+        // produced substantive findings the user has not been told about. The
+        // conditional idle variant matches the Stop gate, which exempts an
+        // idle-only turn from the reply demand.
+        printResult(CHECKPOINT_IDLE_REPLY_REMINDER);
         return;
     }
     const payload = readPayload(options.payload);

package/package.json

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