@memnexus-ai/mx-agent-cli 0.1.251 → 0.1.252
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.
|
@@ -231,6 +231,74 @@ git fetch --prune
|
|
|
231
231
|
|
|
232
232
|
## Safety Rules
|
|
233
233
|
|
|
234
|
+
### Report Every Guard Override — Required, Not Optional
|
|
235
|
+
|
|
236
|
+
Several of the commands above (`git reset --hard`, `git stash`, `git checkout -- <path>`,
|
|
237
|
+
`git restore <path>`) are blocked by the `git-mutation-guard` PreToolUse hook. The block
|
|
238
|
+
message tells you to re-run with a `GIT_EXPERT=1` prefix. Using that override is legitimate —
|
|
239
|
+
you are the designated agent for destructive git operations, and the escape hatch exists for
|
|
240
|
+
you. Using it *silently* is not.
|
|
241
|
+
|
|
242
|
+
**Whenever you clear a guard block with `GIT_EXPERT=1` — or with any other sanctioned
|
|
243
|
+
override — your report back MUST contain all four of the following. A report that omits any
|
|
244
|
+
of them is an incomplete task, not a stylistic shortcut, and you must go back and add them
|
|
245
|
+
before you finish:**
|
|
246
|
+
|
|
247
|
+
1. **Which command was blocked** — the exact command, verbatim.
|
|
248
|
+
2. **Which guard blocked it** — the guard name from the block message (e.g.
|
|
249
|
+
`git-mutation-guard`), not just "a hook."
|
|
250
|
+
3. **That you used the override** — state `GIT_EXPERT=1` (or the override you used) explicitly.
|
|
251
|
+
"I ran a hard reset" is not a disclosure of an override.
|
|
252
|
+
4. **Why the override was justified** — the specific reason this destructive operation was
|
|
253
|
+
correct here (e.g. "all branch commits were confirmed on main after squash merge; no
|
|
254
|
+
unpushed work").
|
|
255
|
+
|
|
256
|
+
Use this form:
|
|
257
|
+
|
|
258
|
+
```
|
|
259
|
+
Guard override used:
|
|
260
|
+
Blocked command: git reset --hard origin/main
|
|
261
|
+
Guard: git-mutation-guard (PreToolUse)
|
|
262
|
+
Override: GIT_EXPERT=1
|
|
263
|
+
Justification: Post-squash-merge sync. Verified `git log origin/main..HEAD` was
|
|
264
|
+
empty and `git status` clean before resetting — no work at risk.
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
**Why this is a hard requirement.** On 2026-07-31 a git-expert was blocked on a hard reset,
|
|
268
|
+
re-ran it four seconds later with `GIT_EXPERT=1`, and closed by telling its leader only that
|
|
269
|
+
it had used a hard reset. No mention of the block, no mention of the override. That leader
|
|
270
|
+
reported in good faith that the guard had not fired, and an investigation across eight
|
|
271
|
+
worktrees was spent confirming a guard that was healthy the whole time. The override was
|
|
272
|
+
correct. Its invisibility was the defect.
|
|
273
|
+
|
|
274
|
+
**Routing around a guard counts too.** The requirement above applies to the override because
|
|
275
|
+
the override is the route the guard instruments. It is not the only route. The guard covers
|
|
276
|
+
four patterns — `reset --hard`, `stash`, `checkout -- <path>`, `restore <path>` — and every
|
|
277
|
+
one of these is allowed through with no block and no log:
|
|
278
|
+
|
|
279
|
+
| Allowed, unlogged | Destroys |
|
|
280
|
+
|---|---|
|
|
281
|
+
| `git clean -fdx` | every untracked file, including another agent's new work |
|
|
282
|
+
| `git checkout -f <branch>` | uncommitted changes across the tree |
|
|
283
|
+
| `git branch -D <branch>` | an unmerged branch |
|
|
284
|
+
| `git worktree remove --force` | an entire worktree and everything uncommitted in it |
|
|
285
|
+
| `git update-ref -d` / `git reflog expire --expire=now --all` | the refs and reflog you would recover from |
|
|
286
|
+
| `rm -rf <path>` | whatever you point it at |
|
|
287
|
+
|
|
288
|
+
So: **if a guard blocks you and you then accomplish the same effect by a route the guard does
|
|
289
|
+
not cover, that is reportable on the same terms** — state which command was blocked, which
|
|
290
|
+
route you took instead, and why that route was the right one. You would be able to say
|
|
291
|
+
truthfully that you used no override, and your leader would still have the wrong picture.
|
|
292
|
+
Reaching for an uninstrumented path to avoid the disclosure is precisely the failure this
|
|
293
|
+
section exists to prevent, and it is worse than the silent override was, because there is no
|
|
294
|
+
log to reconcile against afterwards.
|
|
295
|
+
|
|
296
|
+
Your leader cannot tell "the guard did not fire" from "the guard fired and I overrode it"
|
|
297
|
+
unless you say so. Only you have that information at the moment it matters. The override is
|
|
298
|
+
also recorded to `~/.mx-agent/logs/git-guard-override.jsonl`, but that log is a
|
|
299
|
+
reconciliation record for later audit — it does not reach your leader in time to inform the
|
|
300
|
+
decision in front of them, and it does not carry your justification. Reporting is your job.
|
|
301
|
+
|
|
234
302
|
### Never Do Without Explicit Confirmation
|
|
235
303
|
|
|
236
304
|
| Operation | Risk | When It's Safe |
|
|
@@ -368,6 +436,7 @@ git stash pop
|
|
|
368
436
|
| **Committing .claude/settings.local.json** | Local settings contain user-specific configuration. | Keep it in .gitignore. Only commit .claude/settings.json (shared). |
|
|
369
437
|
| **Interactive rebase in agent context** | `git rebase -i` requires terminal input that agents can't provide. | Use non-interactive rebase. For squashing, use `git rebase` with `--squash` on merge instead. |
|
|
370
438
|
| **Ignoring stash before rebase** | Unstaged changes block rebase with a confusing error. | Always `git stash --include-untracked` before rebase, `git stash pop` after. |
|
|
439
|
+
| **Silent guard override** | Reporting "I ran a hard reset" after clearing a `git-mutation-guard` block with `GIT_EXPERT=1` hides the block from your leader, who then cannot tell a working guard from a broken one. This cost a fleet-wide investigation on 2026-07-31. | Report all four items — blocked command, guard, override used, justification. See "Report Every Guard Override" above. |
|
|
371
440
|
|
|
372
441
|
---
|
|
373
442
|
|
|
@@ -378,3 +447,7 @@ branches stay in sync, conflicts get resolved correctly, and no work is lost. Wh
|
|
|
378
447
|
works, nobody notices. When git breaks, everything stops.
|
|
379
448
|
|
|
380
449
|
Your job is to make sure nobody notices.
|
|
450
|
+
|
|
451
|
+
The one thing you never keep quiet is a guardrail you had to step around. Overrides get
|
|
452
|
+
reported, every time — a leader acting on an incomplete picture of what the guardrails did
|
|
453
|
+
is a worse outcome than any git problem you were solving.
|
|
@@ -19,6 +19,21 @@
|
|
|
19
19
|
# ESCAPE HATCH: prefix the command with `GIT_EXPERT=1` to run a genuinely-needed
|
|
20
20
|
# destructive git op deliberately (e.g. GIT_EXPERT=1 git reset --hard <sha>).
|
|
21
21
|
# The escape is intentional friction, not a lock.
|
|
22
|
+
# OVERRIDE AUDIT (2026-07-31 false alarm): an override that clears a real block is
|
|
23
|
+
# appended to ~/.mx-agent/logs/git-guard-override.jsonl before the command runs,
|
|
24
|
+
# so "the guard never fired" and "the guard fired and was overridden" are
|
|
25
|
+
# distinguishable after the fact. Motivating incident: a git-expert was blocked on
|
|
26
|
+
# a hard reset, re-ran it four seconds later with GIT_EXPERT=1, and reported only
|
|
27
|
+
# the reset to its leader; that leader then reported a broken guard in good faith
|
|
28
|
+
# and an investigation confirmed the guard was healthy in all eight worktrees. The
|
|
29
|
+
# override itself was sanctioned — its invisibility was the defect. Self-reporting
|
|
30
|
+
# alone is a rung-5 control (it depends on the overriding agent choosing to
|
|
31
|
+
# mention it), so the log exists as the independent record. Logging is FAIL-OPEN
|
|
32
|
+
# and side-effect-only: on any problem it is skipped, not retried and not
|
|
33
|
+
# escalated, so an override is neither withheld nor delayed because of it. See
|
|
34
|
+
# the log_override() header for the failure modes this had to be hardened
|
|
35
|
+
# against (a FIFO that blocked the append forever, a symlink that redirected it)
|
|
36
|
+
# and for the residual TOCTOU that is knowingly accepted.
|
|
22
37
|
# LAYERING CAVEAT: GIT_EXPERT=1 only clears THIS hook's blocks (bare-SHA/branch
|
|
23
38
|
# reset forms, stash, checkout-file, restore-worktree). It does NOT clear the two
|
|
24
39
|
# patterns `git reset --hard HEAD~*` and `git reset --hard HEAD^*` — those are
|
|
@@ -65,11 +80,100 @@ if [[ -z "$COMMAND" ]]; then
|
|
|
65
80
|
exit 0
|
|
66
81
|
fi
|
|
67
82
|
|
|
68
|
-
# Deliberate override.
|
|
83
|
+
# Deliberate override. NOTE: this no longer short-circuits. The scan still runs so
|
|
84
|
+
# we can name WHICH pattern the override cleared; refuse() then logs and allows
|
|
85
|
+
# instead of blocking. A GIT_EXPERT=1 command that matches nothing is not an
|
|
86
|
+
# override of anything and is not logged.
|
|
87
|
+
OVERRIDE=0
|
|
69
88
|
if echo "$COMMAND" | grep -qE '(^|[^A-Za-z_])GIT_EXPERT=1(\s|$)'; then
|
|
70
|
-
|
|
89
|
+
OVERRIDE=1
|
|
71
90
|
fi
|
|
72
91
|
|
|
92
|
+
# --- override audit log (fail-open, side-effect only) -------------------------
|
|
93
|
+
# One JSONL line per cleared block, alongside idle-gate.jsonl / session-pause.jsonl.
|
|
94
|
+
# Fields: ts, worktree, guard, pattern (what was blocked), command (first line,
|
|
95
|
+
# sanitized + truncated). The command is UNTRUSTED text, so it is reduced to a
|
|
96
|
+
# conservative allowlist — no quotes, backslashes, control characters or non-ASCII
|
|
97
|
+
# reach the file, and nothing that renders as markup survives.
|
|
98
|
+
#
|
|
99
|
+
# PATH IS HARD-CODED, deliberately. There is no env var to redirect or disable
|
|
100
|
+
# this log: the party whose action is being recorded is the party who benefits
|
|
101
|
+
# from suppressing it, so a single variable in the environment must not be able
|
|
102
|
+
# to turn the record off. Same shape as session-idle-gate.sh, which hard-codes
|
|
103
|
+
# its own path. The probe isolates itself by overriding HOME, not by asking the
|
|
104
|
+
# product for a test hook.
|
|
105
|
+
#
|
|
106
|
+
# WRITE TARGET CHECKS (security review, 2026-08-01). Three defects were measured
|
|
107
|
+
# against earlier revisions of this file, each reproduced before it was fixed:
|
|
108
|
+
# - a FIFO at the log path with no reader made the append block forever on
|
|
109
|
+
# open(); `timeout 8` returned 124. Every override in that home directory
|
|
110
|
+
# hung the Bash call with no error output. `set +e` catches failures; it does
|
|
111
|
+
# nothing about blocking, so the claim that no logging failure could convert
|
|
112
|
+
# an allowed command into a blocked one was false — the command never ran.
|
|
113
|
+
# - a symlink at the log FILE path was followed, appending the record to the
|
|
114
|
+
# link target (201 bytes into a file outside the log directory).
|
|
115
|
+
# - after the leaf check landed, the same redirect survived one level up:
|
|
116
|
+
# `mkdir -p` and `>>` both follow DIRECTORY symlinks, so a symlinked
|
|
117
|
+
# `~/.mx-agent/logs` still took 185 bytes into an attacker-chosen directory.
|
|
118
|
+
# So there are two tests: the leaf must be absent or a plain regular file and not
|
|
119
|
+
# a symlink (`-f` alone follows links), and the containing directory must be a
|
|
120
|
+
# real directory and not a symlink. Either test failing skips the log entirely
|
|
121
|
+
# and lets the override proceed.
|
|
122
|
+
#
|
|
123
|
+
# WHAT THIS DOES NOT CLOSE — read this before describing the log as tamper-proof,
|
|
124
|
+
# because that description has now been wrong three times. Symlink redirection is
|
|
125
|
+
# closed AT THE LEAF AND ONE DIRECTORY UP. It is NOT closed for a symlinked
|
|
126
|
+
# `~/.mx-agent`, a symlinked `$HOME`, or any higher path component: those are
|
|
127
|
+
# resolved by the kernel before either test sees them, and walking every
|
|
128
|
+
# component is not something this hook should be doing on a hot path. Also not
|
|
129
|
+
# closed: the checks are TOCTOU, not atomic — a writer that swaps the path
|
|
130
|
+
# between the test and the append still wins the race, and closing that needs
|
|
131
|
+
# O_NOFOLLOW|O_NONBLOCK, which bash cannot express. Both residuals are accepted
|
|
132
|
+
# on the same grounds: anyone able to plant a component symlink in the agent's
|
|
133
|
+
# own home or to win that race already executes as the agent user, and this file
|
|
134
|
+
# is a guardrail, not an access control (same posture as the guard itself).
|
|
135
|
+
#
|
|
136
|
+
# The whole body runs in a subshell with errexit disabled, so an error inside it
|
|
137
|
+
# cannot change the caller's exit status. Combined with the two target tests, the
|
|
138
|
+
# intended property is that logging is skipped rather than allowed to stall or
|
|
139
|
+
# misdirect — an override is never withheld, and never delayed, because of the
|
|
140
|
+
# log.
|
|
141
|
+
log_override() {
|
|
142
|
+
(
|
|
143
|
+
set +e +u +o pipefail
|
|
144
|
+
log_dir="${HOME:-/tmp}/.mx-agent/logs"
|
|
145
|
+
log_file="${log_dir}/git-guard-override.jsonl"
|
|
146
|
+
|
|
147
|
+
# Leaf: refuse anything that is not an absent path or a plain regular file.
|
|
148
|
+
# FIFOs block, symlinks redirect, devices do neither usefully.
|
|
149
|
+
if [ -e "$log_file" ] || [ -L "$log_file" ]; then
|
|
150
|
+
[ -f "$log_file" ] && [ ! -L "$log_file" ] || exit 0
|
|
151
|
+
fi
|
|
152
|
+
|
|
153
|
+
ts="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
|
|
154
|
+
wt_path="${CLAUDE_WORKTREE_PATH:-${CLAUDE_PROJECT_DIR:-}}"
|
|
155
|
+
wt="$(basename "$wt_path" 2>/dev/null)"
|
|
156
|
+
wt="${wt//[^a-zA-Z0-9_.-]/}"
|
|
157
|
+
wt="${wt:-unknown}"
|
|
158
|
+
cmd="$(printf '%s' "$COMMAND" \
|
|
159
|
+
| head -n 1 \
|
|
160
|
+
| LC_ALL=C tr -d '\000-\037\177' \
|
|
161
|
+
| LC_ALL=C tr -c 'A-Za-z0-9 _.,:/=@+~^-' '?' \
|
|
162
|
+
| cut -c1-200)"
|
|
163
|
+
pat="$(printf '%s' "$1" | LC_ALL=C tr -c 'A-Za-z0-9 _.<>-' '?' | cut -c1-60)"
|
|
164
|
+
mkdir -p "$log_dir" || exit 0
|
|
165
|
+
|
|
166
|
+
# Containing directory: `mkdir -p` succeeds on a symlink-to-directory and
|
|
167
|
+
# `>>` follows it, so the leaf check alone left the redirect intact one level
|
|
168
|
+
# up. Test after mkdir, since the directory may not have existed before it.
|
|
169
|
+
[ -d "$log_dir" ] && [ ! -L "$log_dir" ] || exit 0
|
|
170
|
+
|
|
171
|
+
printf '{"ts":"%s","worktree":"%s","guard":"git-mutation-guard","pattern":"%s","override":"GIT_EXPERT=1","command":"%s"}\n' \
|
|
172
|
+
"$ts" "$wt" "$pat" "$cmd" >> "$log_file"
|
|
173
|
+
) >/dev/null 2>&1 || true
|
|
174
|
+
return 0
|
|
175
|
+
}
|
|
176
|
+
|
|
73
177
|
# --- heredoc-body stripping (consumer-aware) --------------------------------
|
|
74
178
|
# Produce a "scannable" copy of the command. A heredoc body is dropped ONLY when
|
|
75
179
|
# its consuming command is inert (cat/tee/redirect-to-file/non-shell language) —
|
|
@@ -250,6 +354,14 @@ SCAN=$(printf '%s' "$COMMAND" | strip_heredocs)
|
|
|
250
354
|
|
|
251
355
|
refuse() {
|
|
252
356
|
local what="$1"
|
|
357
|
+
|
|
358
|
+
# Override in effect: record what it cleared, then allow. Silent on stdout and
|
|
359
|
+
# stderr — the allow contract is "exit 0, no output".
|
|
360
|
+
if [[ "$OVERRIDE" -eq 1 ]]; then
|
|
361
|
+
log_override "$what"
|
|
362
|
+
exit 0
|
|
363
|
+
fi
|
|
364
|
+
|
|
253
365
|
{
|
|
254
366
|
echo ""
|
|
255
367
|
echo "BLOCKED: destructive git operation ($what)"
|
|
@@ -262,6 +374,14 @@ refuse() {
|
|
|
262
374
|
echo "If you truly must run this, prefix it with GIT_EXPERT=1 to override,"
|
|
263
375
|
echo "e.g. GIT_EXPERT=1 $what ..."
|
|
264
376
|
echo ""
|
|
377
|
+
echo "IF YOU OVERRIDE, YOU MUST REPORT IT. Your report back to whoever asked"
|
|
378
|
+
echo "for this work has to state: the command that was blocked, that"
|
|
379
|
+
echo "git-mutation-guard blocked it, that you used GIT_EXPERT=1 to override,"
|
|
380
|
+
echo "and why the override was justified. Omitting this is a failure to"
|
|
381
|
+
echo "complete the task — a silent override on 2026-07-31 was reported up the"
|
|
382
|
+
echo "chain as a broken guard and cost an investigation across eight"
|
|
383
|
+
echo "worktrees. The override is recorded either way."
|
|
384
|
+
echo ""
|
|
265
385
|
} >&2
|
|
266
386
|
exit 2
|
|
267
387
|
}
|