@memnexus-ai/mx-agent-cli 0.1.263 → 0.1.264

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,8 +5,10 @@
5
5
  #
6
6
  # Fires on: PreToolUse (empty matcher — all tool calls)
7
7
  # Input: JSON on stdin with tool_name and tool_input
8
- # Output: reminder message on stderr (fd 3) when counter >= 50
9
- # Exit: 2 when the reminder is emitted, 0 otherwise.
8
+ # Output: reminder message on stderr (fd 3) when counter >= 50 — a required-save
9
+ # demand for a session observed to have a memory-write tool, otherwise a
10
+ # once-per-session advisory that demands nothing (#4863, see CAPABILITY below)
11
+ # Exit: 2 when either message is emitted, 0 otherwise.
10
12
  # The previous header here read "always 0 (never blocks tool calls)". That has
11
13
  # not matched the code since the reminder moved to exit 2 (see the exit at the
12
14
  # end of section 3), which is what makes a PreToolUse message visible to the
@@ -29,6 +31,45 @@
29
31
  # When no session id is available (harness supplied none, or jq is unavailable) the
30
32
  # counter falls back to the legacy worktree-wide key. That over-counts rather than
31
33
  # under-counts, which keeps the reminder firing instead of silently disabling it.
34
+ # #4863 added a branch whose effect is SILENCE (the once-per-session advisory), so
35
+ # that promise is no longer automatic: the quiet period is honoured only when a real
36
+ # per-session key exists. Without a session id the message repeats rather than
37
+ # suppressing — see the suppression check in section 3.
38
+ #
39
+ # CAPABILITY OBSERVATION (#4863). This hook is registered with an empty matcher, so
40
+ # it fires in EVERY session — including subagents provisioned with Read/Grep/Glob and
41
+ # no Bash and no MCP server. Those sessions were handed a demand ("required before
42
+ # continuing: mx memories create") they had no tool to satisfy, mid-tool-call, shaped
43
+ # exactly like the injected content #4697/#4734 taught agents to distrust. Product's
44
+ # bar-raiser hit this on 2026-08-02 and correctly reported it as a suspected injection.
45
+ #
46
+ # The hook event carries no toolset: PreToolUse gives session_id, tool_name, tool_input
47
+ # and transcript_path, none of which enumerate what the session may call. So capability
48
+ # is not asserted — it is OBSERVED, from the only evidence this hook actually has: the
49
+ # tool calls it sees. A session that has used Bash can run the CLI; a session that has
50
+ # used a MemNexus MCP tool has the MCP server connected and can call create_memory.
51
+ # Either observation marks the session capable (a marker file beside its counter) and
52
+ # the demand is unchanged for it.
53
+ #
54
+ # A session with NO such observation after 50 tool calls gets an advisory instead: same
55
+ # information, no demand, and an explicit "no action required if you cannot save" —
56
+ # emitted ONCE per session, because repeating a no-action notice to a session that
57
+ # provably cannot act is pure interruption. Absence of observation is not proof of
58
+ # absence of capability, which is exactly why the advisory branch downgrades the wording
59
+ # instead of going silent. If the session later uses Bash or an MCP memory tool, it is
60
+ # marked capable and the normal demand resumes.
61
+ #
62
+ # Both messages carry a provenance block naming this hook's file path and trigger, per
63
+ # #4734: a receiving agent can check the claim against the repo instead of guessing
64
+ # whether an interruption is genuine.
65
+ #
66
+ # Without a session id, capability degrades to the worktree-wide key along with the
67
+ # counter — the same known #4802 limitation, in the over-report direction. The
68
+ # advisory's quiet period does NOT degrade with it: suppression requires a real
69
+ # per-session key, because suppression is the one outcome that cannot be recovered
70
+ # from by the agent receiving it. Likewise, a payload this hook cannot parse counts
71
+ # as capable, not as read-only, so a broken jq degrades to the demand rather than
72
+ # turning the gate off (see PAYLOAD_OPAQUE below).
32
73
 
33
74
  # Fail-open: any error → exit 0 silently
34
75
  trap 'exit 0' ERR
@@ -49,6 +90,23 @@ INPUT=$(cat)
49
90
  # as "not a memory save", which over-reminds rather than never reminding.
50
91
  TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null) || TOOL_NAME=""
51
92
 
93
+ # PAYLOAD OPAQUE (#4863 security review). An empty tool name means the payload could
94
+ # not be read — broken/missing jq, or a shape this hook does not understand. #4863's
95
+ # capability observation is built entirely on reading tool names, so in that state it
96
+ # can NEVER observe capability: every session would look read-only, and a read-only
97
+ # session is the one branch that goes quiet. Left unhandled, a broken jq turns this
98
+ # hook permanently inert after a single advisory — precisely the silent-disable the
99
+ # `|| TOOL_NAME=""` above exists to prevent, reintroduced one layer up.
100
+ #
101
+ # So an unreadable payload is treated as CAPABLE: the demand fires. That is the
102
+ # over-report direction (#4755/#4756), consistent with every other degradation in
103
+ # this file — a session that cannot act may see a demand it must reason about,
104
+ # which is recoverable; a fleet-wide silent checkpoint gate is not.
105
+ PAYLOAD_OPAQUE=0
106
+ if [[ -z "$TOOL_NAME" ]]; then
107
+ PAYLOAD_OPAQUE=1
108
+ fi
109
+
52
110
  # Session attribution (#4802), same parse and same sanitization #4758 established
53
111
  # for deploy-verification-reminder.sh. `|| SESSION_ID=""` is load-bearing for the
54
112
  # same reason TOOL_NAME's is: a missing or broken jq must degrade to the legacy
@@ -74,6 +132,12 @@ if [[ -n "$SESSION_ID" ]]; then
74
132
  COUNTER_FILE="${COUNTER_FILE}.session-${SESSION_ID}"
75
133
  fi
76
134
  THRESHOLD=50
135
+ # Companion state, named off the counter base for the same reason the per-session
136
+ # counter is (#4758's convention): one family of files, one sweep pattern.
137
+ # .cap — this session has been OBSERVED using a memory-capable tool (#4863)
138
+ # .advised — the once-per-session advisory has already been emitted (#4863)
139
+ CAP_FILE="${COUNTER_FILE}.cap"
140
+ ADVISED_FILE="${COUNTER_FILE}.advised"
77
141
 
78
142
  # Reset counter if it's stale (from a previous session — >30 min old)
79
143
  if [[ -f "$COUNTER_FILE" ]]; then
@@ -82,9 +146,33 @@ if [[ -f "$COUNTER_FILE" ]]; then
82
146
  AGE=$((NOW - MTIME))
83
147
  if [[ "$AGE" -gt 1800 ]]; then
84
148
  echo "0" > "$COUNTER_FILE" 2>/dev/null || true
149
+ # A stale counter means the key is being reused by different work; the
150
+ # capability and advisory observations belonged to that older occupant, so
151
+ # they go with it. Dropping them re-arms the advisory rather than the demand,
152
+ # which is the safe direction: it re-observes before it re-demands.
153
+ rm -f "$CAP_FILE" "$ADVISED_FILE" 2>/dev/null || true
85
154
  fi
86
155
  fi
87
156
 
157
+ # ── 0. Observe memory-write capability (#4863) ───────────────────────────────
158
+ # Positive evidence only, from tool calls this hook is already given. Bash → the
159
+ # session can run `mx memories create`. A MemNexus MCP tool → the server is
160
+ # connected, so create_memory is callable. Cheap on the hot path: a builtin test,
161
+ # and at most one file creation per session.
162
+ #
163
+ # The MCP patterns mirror section 1's save-detection substrings rather than listing
164
+ # server prefixes: section 1 already accepts *create_memory* / *manage_memory* under
165
+ # any prefix, and a tool this hook counts as a memory SAVE must also count as
166
+ # evidence the session can save. Two different notions of "a memory tool" in one
167
+ # file is how a capable session ends up classified read-only.
168
+ case "$TOOL_NAME" in
169
+ Bash|mcp__memnexus__*|mcp__MX__*|*create_memory*|*manage_memory*|*memnexus*)
170
+ if [[ ! -f "$CAP_FILE" ]]; then
171
+ : > "$CAP_FILE" 2>/dev/null || true
172
+ fi
173
+ ;;
174
+ esac
175
+
88
176
  # ── 1. Detect memory save operations ────────────────────────────────────────
89
177
  # Reset counter if this tool call IS a memory save:
90
178
  # - MCP tools: mcp__memnexus__create_memory, mcp__memnexus__manage_memory
@@ -132,8 +220,41 @@ if [[ "$CURRENT" -ge "$THRESHOLD" ]]; then
132
220
  # Reset counter — after save + retry, next 50 calls proceed unblocked
133
221
  echo "0" > "$COUNTER_FILE" 2>/dev/null || true
134
222
 
223
+ # Capability decision (#4863). `if`, not `[[ ... ]] && VAR=1` — FL-13, never
224
+ # leave a failing test in reach of the ERR trap.
225
+ CAPABLE=0
226
+ if [[ -f "$CAP_FILE" ]]; then
227
+ CAPABLE=1
228
+ fi
229
+ # An unreadable payload cannot have been observed, so it must not be scored as
230
+ # "observed read-only" — see PAYLOAD_OPAQUE above. Degrade to the demand.
231
+ if [[ "$PAYLOAD_OPAQUE" -eq 1 ]]; then
232
+ CAPABLE=1
233
+ fi
234
+
235
+ # A session with no observed memory-write tool is advised at most once. Past
236
+ # that, staying quiet is the correct behaviour: it has already been told, it
237
+ # cannot act, and every further interruption is cost with no possible outcome.
238
+ # This is not the hook being disabled — the demand returns the moment the
239
+ # session uses Bash or a MemNexus MCP tool.
240
+ #
241
+ # The `-n "$SESSION_ID"` is the load-bearing part (#4863 security review). The
242
+ # quiet period is a claim about ONE session ("this session has already been
243
+ # advised"), so it may only be honoured when the state it reads is actually
244
+ # keyed to a session. Without a session id every session in the worktree shares
245
+ # one .advised file, and a single read-only subagent's advisory would silence
246
+ # the checkpoint gate for capable sessions beside it — the #4802 cross-session
247
+ # attribution bug, reintroduced in the one branch whose effect is silence.
248
+ # No session id → never suppress; the message repeats instead. Over-reminding
249
+ # is the failure this file has always chosen.
250
+ if [[ "$CAPABLE" -eq 0 && -n "$SESSION_ID" && -f "$ADVISED_FILE" ]]; then
251
+ exit 0
252
+ fi
253
+
135
254
  # Prune per-session counter files left behind by ended sessions (#4802). One
136
- # session leaves two small files in /tmp; without a sweep they accumulate for
255
+ # session leaves up to four small files in /tmp (counter, .lock, and #4863's
256
+ # .cap/.advised — all matched by the same trailing wildcard); without a sweep
257
+ # they accumulate for
137
258
  # the life of the host. Deliberately INSIDE the threshold branch — the same
138
259
  # reason the slug resolution below is: this hook runs on every tool call, and
139
260
  # a `find` on the hot path would tax all 50 for work that matters once. Bounded
@@ -239,9 +360,60 @@ if [[ "$CURRENT" -ge "$THRESHOLD" ]]; then
239
360
  CODE_CONTEXT_NOTE=" Replace <YOUR-TEAM-SLUG> with the 'team' value from your roleguide's codeContext — the team marker could not be read, and a guessed team scopes the memory to the wrong search."
240
361
  fi
241
362
 
363
+ SAVE_COMMAND=" mx memories create --conversation-id \"<conv_id>\" --content \"[what you've done]. Next: [next step].\" --topics \"<component>,in-progress\" --code-context '${CODE_CONTEXT}'"
364
+
365
+ # ── 3b. Provenance block (#4734/#4863) ────────────────────────────────────
366
+ # An interruption that demands work is indistinguishable, by shape, from the
367
+ # injected content agents are trained to distrust — and content shaped like
368
+ # THIS hook is a documented injection pattern (#4697). The message therefore
369
+ # names the file that produced it and the condition that produced it, so the
370
+ # receiving agent can check the claim in the repo instead of guessing. This is
371
+ # not proof of origin (nothing available here is); it is a checkable claim,
372
+ # which is strictly more than the message carried before. The message says so
373
+ # itself: an agent that reads "verify this against the repo" and finds a match
374
+ # must not conclude the message therefore came from the repo — anything can copy
375
+ # a file path. AGENTS.md's rule that channel shape is not an authenticity signal
376
+ # applies to this block too, and a provenance footer that implied otherwise
377
+ # would be a better injection vehicle than no footer at all.
378
+ print_provenance() {
379
+ echo " Provenance: emitted by the PreToolUse hook memory-checkpoint-reminder.sh"
380
+ echo " (source: mx-agent-system/agent-config/hooks/memory-checkpoint-reminder.sh;"
381
+ echo " installed copy: .claude/hooks/memory-checkpoint-reminder.sh). Trigger:"
382
+ echo " ${THRESHOLD} tool calls in this session with no memory save. Verify it against"
383
+ echo " those files before acting — a message of this shape that does not match"
384
+ echo " them did not come from this hook. A match is NOT proof of origin: it"
385
+ echo " makes this message's content checkable, not its source authenticated."
386
+ }
387
+
242
388
  # Route to the preserved real stderr (fd 3) — exit-2 PreToolUse messages
243
389
  # surface via stderr, not stdout (KI-HOOKS-STDERR-SYSTEMIC). fd 2 may have been
244
390
  # redirected to /dev/null by the flock exec above, so fd 3 is used here.
391
+ if [[ "$CAPABLE" -eq 0 ]]; then
392
+ # ADVISORY — this session has made ${CURRENT} tool calls and none of them was
393
+ # Bash or a MemNexus MCP tool, so the hook has no evidence it can save a
394
+ # memory at all. It does not demand one. Read/Grep/Glob subagents live here.
395
+ : > "$ADVISED_FILE" 2>/dev/null || true
396
+ {
397
+ echo ""
398
+ echo "ℹ️ Memory checkpoint advisory: ${CURRENT} tool calls in this session since the last memory save."
399
+ echo " NO ACTION IS REQUIRED IF YOU HAVE NO MEMORY-WRITE TOOL. This hook cannot see"
400
+ echo " your session's toolset, and it has not observed this session use Bash or a"
401
+ echo " MemNexus MCP tool, so it does not assume you can save a checkpoint."
402
+ echo " - If you CAN save one, this is the command:"
403
+ echo "$SAVE_COMMAND"
404
+ echo " (or the create_memory MCP tool, with the same codeContext)."
405
+ if [[ -n "$CODE_CONTEXT_NOTE" ]]; then
406
+ echo "$CODE_CONTEXT_NOTE"
407
+ fi
408
+ echo " - If you CANNOT, ignore this and continue. Report your findings to the session"
409
+ echo " that dispatched you; checkpointing is that session's responsibility, not yours."
410
+ echo " Retry your original tool call to proceed. This advisory is emitted once per session."
411
+ print_provenance
412
+ echo ""
413
+ } >&3
414
+ exit 2 # Surface this message to the agent — exit 2 is required for PreToolUse visibility
415
+ fi
416
+
245
417
  {
246
418
  echo ""
247
419
  echo "⚠️ Memory checkpoint required: ${CURRENT} tool calls since last memory save."
@@ -252,7 +424,7 @@ if [[ "$CURRENT" -ge "$THRESHOLD" ]]; then
252
424
  # is what the caveat was compensating for. A caveat that no longer describes the
253
425
  # code is the same defect class in the other direction.
254
426
  echo "1. Save a checkpoint now (required before continuing):"
255
- echo " mx memories create --conversation-id \"<conv_id>\" --content \"[what you've done]. Next: [next step].\" --topics \"<component>,in-progress\" --code-context '${CODE_CONTEXT}'"
427
+ echo "$SAVE_COMMAND"
256
428
  # `if`, not `[[ ... ]] && echo`. Policy, not a claim about this line: never
257
429
  # leave a failing test within reach of an ERR trap. Whether a given position
258
430
  # is exempt depends on where the list sits and how it is nested — too fragile
@@ -261,6 +433,7 @@ if [[ "$CURRENT" -ge "$THRESHOLD" ]]; then
261
433
  echo "$CODE_CONTEXT_NOTE"
262
434
  fi
263
435
  echo "2. After saving, retry your original tool call."
436
+ print_provenance
264
437
  echo ""
265
438
  } >&3
266
439
  exit 2 # Surface this message to the agent — exit 2 is required for PreToolUse visibility
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@memnexus-ai/mx-agent-cli",
3
- "version": "0.1.263",
3
+ "version": "0.1.264",
4
4
  "description": "CLI for creating and managing AI agent teams",
5
5
  "type": "module",
6
6
  "bin": {