@indigoai-us/hq-cli 5.103.8 → 5.103.9

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 ## [Unreleased]
 
+## [5.103.9] — 2026-08-20
+
+### Fixed
+
+- The checkpoint stop-gate no longer causes duplicated or hidden replies
+  around the end-of-turn checkpoint. The gate now reads the transcript to
+  detect whether the agent already delivered its user-facing reply this turn
+  and issues the matching instruction: checkpoint-then-full-reply when no
+  reply exists yet, or checkpoint-and-end-without-repeating when it does. The
+  `hq core checkpoint` reply reminder carries the same conditional contract.
+
 ## [5.103.8] — 2026-08-19
 
 ### Fixed

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

@@ -236,14 +236,16 @@ set -uo pipefail
     | [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
         | [
-            $rows[($user_index + 1):][]
-            | .entry
+            range(0; $turn | length) as $ti
+            | $turn[$ti].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? // ""),
@@ -255,6 +257,7 @@ set -uo pipefail
               ) then
                 .payload
                 | {
+                    i: $ti,
                     runtime: "codex",
                     id: (.call_id? // .id? // ""),
                     name: (.name? // ""),
@@ -264,6 +267,30 @@ set -uo pipefail
               end
           ] 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
         | ([$tools[] | select((.command | checkpoint_command) | not)] | length) as $work_tool_count
         | ([
              $rows[]
@@ -280,14 +307,19 @@ set -uo pipefail
           ) then
             if $last_tool.runtime == "claude" and ($last_result_error | not) then "1"
             elif $last_tool.runtime == "codex" then "stamp"
-            else "0"
+            else (if $replied then "0-replied" else "0-unreplied" end)
             end
           elif $work_tool_count == 0 then "idle"
-          else "0"
+          else (if $replied then "0-replied" else "0-unreplied" end)
           end
       end
   ' 2>/dev/null)" || exit 0
   satisfied="$parsed"
+  replied=0
+  case "$satisfied" in
+    0-replied) satisfied=0; replied=1 ;;
+    0-unreplied) satisfied=0 ;;
+  esac
   case "$satisfied" in
     0|1|stamp|idle) ;;
     *) exit 0 ;;
@@ -349,7 +381,19 @@ set -uo pipefail
 
   # Built with printf rather than concatenation so the session id can appear in
   # both commands without re-splitting the message into fragments.
-  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. If you owe them anything — a result, a link, an answer, a status — say it in the reply as usual. The checkpoint is invisible to them and is NOT a message to them; running it 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 (this app folds any text that precedes a tool call into a collapsed sub-message — only text AFTER the last tool call renders in full): run the checkpoint FIRST, then deliver your COMPLETE user-facing reply as the final text of the turn. Every link, URL, instruction, command, and decision the user needs MUST appear in that final post-checkpoint message, restated in full even if you already wrote it earlier in the turn — earlier text is collapsed and the user will not see it.\n\n  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' "$session_id" "$session_id")"
+  #
+  # 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.
+  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")"
+  fi
 
   # Codex surfaces a blocked Stop reason as a synthetic user prompt. Preserve
   # the actionable instruction out-of-band, then use the stable marker covered

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

@@ -14,11 +14,14 @@ type SpawnableBackend = Exclude<Backend, "none">;
  * treating the checkpoint call as the end of the turn, leaving their actual
  * findings only in the checkpoint payload — which the user never sees. This
  * line rides the command output (the one channel guaranteed to reach the
- * calling agent) to force the user-facing reply. Deliberately conditional so
- * it composes with the Stop-gate prompt's "checkpoint first, reply last"
- * ordering: some hosts (the desktop app runtime) do not reliably display
- * assistant text that precedes a tool call, so the reply must come after
- * the checkpoint output as the final text of the turn. Mirrors the hq-core policies
+ * calling agent) to force the user-facing reply. Deliberately conditional on
+ * whether the reply was already delivered this turn: an unconditional
+ * "restate in full" made agents repeat a reply the user had already seen
+ * (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
  * `checkpoint-is-bookkeeping-not-user-communication` and
  * `checkpoint-is-not-the-user-report`.
  */

package/dist/commands/core-checkpoint.js

@@ -45,20 +45,23 @@ class CheckpointUsageError extends Error {
  * treating the checkpoint call as the end of the turn, leaving their actual
  * findings only in the checkpoint payload — which the user never sees. This
  * line rides the command output (the one channel guaranteed to reach the
- * calling agent) to force the user-facing reply. Deliberately conditional so
- * it composes with the Stop-gate prompt's "checkpoint first, reply last"
- * ordering: some hosts (the desktop app runtime) do not reliably display
- * assistant text that precedes a tool call, so the reply must come after
- * the checkpoint output as the final text of the turn. Mirrors the hq-core policies
+ * calling agent) to force the user-facing reply. Deliberately conditional on
+ * whether the reply was already delivered this turn: an unconditional
+ * "restate in full" made agents repeat a reply the user had already seen
+ * (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
  * `checkpoint-is-bookkeeping-not-user-communication` and
  * `checkpoint-is-not-the-user-report`.
  */
 export const CHECKPOINT_REPLY_REMINDER = "checkpoint: REMINDER — this checkpoint is invisible bookkeeping; the user never sees it " +
-    "and it does NOT count as your reply. Now write your user-facing reply as the FINAL text " +
-    "of the turn — everything of substance from this turn (results, findings, decisions, " +
-    "state changes, anything awaiting their input) — even if you already wrote it earlier: " +
-    "assistant text that precedes a tool call is not reliably shown to the user on all " +
-    "hosts. Then end the turn.";
+    "and it does NOT count as your reply. If this turn's substance (results, findings, " +
+    "decisions, state changes, anything awaiting their input) has NOT yet been delivered to " +
+    "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.";
 function printResult(line) {
     process.stdout.write(`${line}\n`);
 }

package/package.json

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