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

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.
@@ -13,6 +13,83 @@
13
13
  # Output: none (side-effect only — saves memory via mx CLI)
14
14
  # Exit: always 0 (never blocks)
15
15
 
16
+ MXHT_HOOK=auto-capture-session-end MXHT_EVENT=Stop MXHT_TOOL=-
17
+ # >>> SHARED hook-timing probe v1
18
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
19
+ # separated from time spent waiting on the API when a session stalls mid-stream.
20
+ # Appends one line to a local, gitignored log. Read it with
21
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
22
+ #
23
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
24
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
25
+ # default. A diagnostic that can break the gate it observes is worse than no
26
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
27
+ # guard on the PreToolUse path at once. Every step below is guarded and every
28
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
29
+ #
30
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
31
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
32
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
33
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
34
+ MXHT_T0="${EPOCHREALTIME:-}"
35
+ _mxht_emit() {
36
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
37
+ MXHT_DONE=1
38
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
39
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
40
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
41
+ [ -n "$root" ] && [ -d "$root" ] || return 0
42
+ local dir="$root/.mx-hook-timing"
43
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
44
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
45
+ # strip both forms and subtract as plain integer microseconds.
46
+ local dur=-1
47
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
48
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
49
+ local stamp hour
50
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
51
+ printf -v hour '%(%H)T' -1
52
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
53
+ # is at most 24 files each holding one hour of this machine's hook calls. The
54
+ # first writer into a slot on a new day truncates it instead of appending —
55
+ # detected by reading the slot's first line, which is a builtin read (no stat,
56
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
57
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
58
+ local f="$dir/h$hour.log" first="" line
59
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
60
+ # Anything else is a silent no-op. Two concrete failures if this check is
61
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
62
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
63
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
64
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
65
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
66
+ # dangling symlink, so -L is needed to catch that case too).
67
+ if [ -e "$f" ] || [ -L "$f" ]; then
68
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
69
+ fi
70
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
71
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
72
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
73
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
74
+ # concurrent hooks cannot interleave partial lines.
75
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
76
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
77
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
78
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
79
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
80
+ else
81
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
82
+ fi
83
+ }
84
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
85
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
86
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
87
+ # final printf failing on an unwritable slot is the reachable case — replaces the
88
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
89
+ # harness reads as "error", not "block", so the command it meant to block runs.
90
+ # Pinned verbatim by hook-timing-parity.test.sh.
91
+ trap '_mxht_emit || :' EXIT
92
+ # <<< SHARED hook-timing probe v1
16
93
 
17
94
 
18
95
  # Fail-open: any error -> allow session to end normally
@@ -59,7 +136,11 @@ fi
59
136
  # ── 3. Extract session summary data ──────────────────────────────────────
60
137
 
61
138
  tmpdir=$(mktemp -d)
62
- trap 'rm -rf "$tmpdir"; exit 0' EXIT ERR
139
+ # This EXIT trap REPLACES the hook-timing probe's EXIT trap installed at the top
140
+ # of the file, so it calls the probe explicitly; without this the only hook on
141
+ # the Stop path that allocates a tmpdir would report no timings at all. The probe
142
+ # is idempotent (MXHT_DONE), so the ERR-then-EXIT double fire emits one line.
143
+ trap 'rm -rf "$tmpdir"; _mxht_emit || :; exit 0' EXIT ERR
63
144
 
64
145
  # Only look at lines since last save
65
146
  OFFSET=$((LAST_SAVED_LINES + 1))
@@ -26,6 +26,83 @@
26
26
  # 0 = allow (not a push, or all validations pass, or a load-flake was absorbed)
27
27
  # 2 = block (a real validation failure, or the serialization lock timed out)
28
28
 
29
+ MXHT_HOOK=ci-validate-hook MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
30
+ # >>> SHARED hook-timing probe v1
31
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
32
+ # separated from time spent waiting on the API when a session stalls mid-stream.
33
+ # Appends one line to a local, gitignored log. Read it with
34
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
35
+ #
36
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
37
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
38
+ # default. A diagnostic that can break the gate it observes is worse than no
39
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
40
+ # guard on the PreToolUse path at once. Every step below is guarded and every
41
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
42
+ #
43
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
44
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
45
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
46
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
47
+ MXHT_T0="${EPOCHREALTIME:-}"
48
+ _mxht_emit() {
49
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
50
+ MXHT_DONE=1
51
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
52
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
53
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
54
+ [ -n "$root" ] && [ -d "$root" ] || return 0
55
+ local dir="$root/.mx-hook-timing"
56
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
57
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
58
+ # strip both forms and subtract as plain integer microseconds.
59
+ local dur=-1
60
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
61
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
62
+ local stamp hour
63
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
64
+ printf -v hour '%(%H)T' -1
65
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
66
+ # is at most 24 files each holding one hour of this machine's hook calls. The
67
+ # first writer into a slot on a new day truncates it instead of appending —
68
+ # detected by reading the slot's first line, which is a builtin read (no stat,
69
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
70
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
71
+ local f="$dir/h$hour.log" first="" line
72
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
73
+ # Anything else is a silent no-op. Two concrete failures if this check is
74
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
75
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
76
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
77
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
78
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
79
+ # dangling symlink, so -L is needed to catch that case too).
80
+ if [ -e "$f" ] || [ -L "$f" ]; then
81
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
82
+ fi
83
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
84
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
85
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
86
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
87
+ # concurrent hooks cannot interleave partial lines.
88
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
89
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
90
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
91
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
92
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
93
+ else
94
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
95
+ fi
96
+ }
97
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
98
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
99
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
100
+ # final printf failing on an unwritable slot is the reachable case — replaces the
101
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
102
+ # harness reads as "error", not "block", so the command it meant to block runs.
103
+ # Pinned verbatim by hook-timing-parity.test.sh.
104
+ trap '_mxht_emit || :' EXIT
105
+ # <<< SHARED hook-timing probe v1
29
106
 
30
107
 
31
108
  # Fail-open: any unexpected error → let the push through. NOTE: the two
@@ -31,6 +31,85 @@
31
31
  # `{"decision":"block","reason":"<content>"}` on stdout (the documented Stop-hook
32
32
  # mechanism). We emit that JSON ONLY when the drain returned at least one message.
33
33
 
34
+ MXHT_HOOK=coordination-midsession-drain MXHT_EVENT=Stop MXHT_TOOL=-
35
+ # >>> SHARED hook-timing probe v1
36
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
37
+ # separated from time spent waiting on the API when a session stalls mid-stream.
38
+ # Appends one line to a local, gitignored log. Read it with
39
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
40
+ #
41
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
42
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
43
+ # default. A diagnostic that can break the gate it observes is worse than no
44
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
45
+ # guard on the PreToolUse path at once. Every step below is guarded and every
46
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
47
+ #
48
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
49
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
50
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
51
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
52
+ MXHT_T0="${EPOCHREALTIME:-}"
53
+ _mxht_emit() {
54
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
55
+ MXHT_DONE=1
56
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
57
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
58
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
59
+ [ -n "$root" ] && [ -d "$root" ] || return 0
60
+ local dir="$root/.mx-hook-timing"
61
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
62
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
63
+ # strip both forms and subtract as plain integer microseconds.
64
+ local dur=-1
65
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
66
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
67
+ local stamp hour
68
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
69
+ printf -v hour '%(%H)T' -1
70
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
71
+ # is at most 24 files each holding one hour of this machine's hook calls. The
72
+ # first writer into a slot on a new day truncates it instead of appending —
73
+ # detected by reading the slot's first line, which is a builtin read (no stat,
74
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
75
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
76
+ local f="$dir/h$hour.log" first="" line
77
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
78
+ # Anything else is a silent no-op. Two concrete failures if this check is
79
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
80
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
81
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
82
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
83
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
84
+ # dangling symlink, so -L is needed to catch that case too).
85
+ if [ -e "$f" ] || [ -L "$f" ]; then
86
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
87
+ fi
88
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
89
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
90
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
91
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
92
+ # concurrent hooks cannot interleave partial lines.
93
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
94
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
95
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
96
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
97
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
98
+ else
99
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
100
+ fi
101
+ }
102
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
103
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
104
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
105
+ # final printf failing on an unwritable slot is the reachable case — replaces the
106
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
107
+ # harness reads as "error", not "block", so the command it meant to block runs.
108
+ # Pinned verbatim by hook-timing-parity.test.sh.
109
+ trap '_mxht_emit || :' EXIT
110
+ # <<< SHARED hook-timing probe v1
111
+
112
+
34
113
  # Fail-open: any unhandled error → exit 0 silently.
35
114
  trap 'exit 0' ERR
36
115
  set -u
@@ -10,6 +10,85 @@
10
10
  # Output: advisory message to stdout (when threshold met)
11
11
  # Exit: always 0 (never blocks)
12
12
 
13
+ MXHT_HOOK=delegation-audit MXHT_EVENT=Stop MXHT_TOOL=-
14
+ # >>> SHARED hook-timing probe v1
15
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
16
+ # separated from time spent waiting on the API when a session stalls mid-stream.
17
+ # Appends one line to a local, gitignored log. Read it with
18
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
19
+ #
20
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
21
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
22
+ # default. A diagnostic that can break the gate it observes is worse than no
23
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
24
+ # guard on the PreToolUse path at once. Every step below is guarded and every
25
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
26
+ #
27
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
28
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
29
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
30
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
31
+ MXHT_T0="${EPOCHREALTIME:-}"
32
+ _mxht_emit() {
33
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
34
+ MXHT_DONE=1
35
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
36
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
37
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
38
+ [ -n "$root" ] && [ -d "$root" ] || return 0
39
+ local dir="$root/.mx-hook-timing"
40
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
41
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
42
+ # strip both forms and subtract as plain integer microseconds.
43
+ local dur=-1
44
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
45
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
46
+ local stamp hour
47
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
48
+ printf -v hour '%(%H)T' -1
49
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
50
+ # is at most 24 files each holding one hour of this machine's hook calls. The
51
+ # first writer into a slot on a new day truncates it instead of appending —
52
+ # detected by reading the slot's first line, which is a builtin read (no stat,
53
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
54
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
55
+ local f="$dir/h$hour.log" first="" line
56
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
57
+ # Anything else is a silent no-op. Two concrete failures if this check is
58
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
59
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
60
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
61
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
62
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
63
+ # dangling symlink, so -L is needed to catch that case too).
64
+ if [ -e "$f" ] || [ -L "$f" ]; then
65
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
66
+ fi
67
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
68
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
69
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
70
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
71
+ # concurrent hooks cannot interleave partial lines.
72
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
73
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
74
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
75
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
76
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
77
+ else
78
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
79
+ fi
80
+ }
81
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
82
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
83
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
84
+ # final printf failing on an unwritable slot is the reachable case — replaces the
85
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
86
+ # harness reads as "error", not "block", so the command it meant to block runs.
87
+ # Pinned verbatim by hook-timing-parity.test.sh.
88
+ trap '_mxht_emit || :' EXIT
89
+ # <<< SHARED hook-timing probe v1
90
+
91
+
13
92
  # Fail-open: any error -> allow session to end normally
14
93
  trap 'exit 0' ERR
15
94
 
@@ -7,6 +7,85 @@
7
7
  # Output: reminder message to stdout when deploy pending and not verified
8
8
  # Exit: 2 when reminder is emitted, 0 otherwise
9
9
 
10
+ MXHT_HOOK=deploy-verification-reminder MXHT_EVENT=PostToolUse MXHT_TOOL=Bash
11
+ # >>> SHARED hook-timing probe v1
12
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
13
+ # separated from time spent waiting on the API when a session stalls mid-stream.
14
+ # Appends one line to a local, gitignored log. Read it with
15
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
16
+ #
17
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
18
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
19
+ # default. A diagnostic that can break the gate it observes is worse than no
20
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
21
+ # guard on the PreToolUse path at once. Every step below is guarded and every
22
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
23
+ #
24
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
25
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
26
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
27
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
28
+ MXHT_T0="${EPOCHREALTIME:-}"
29
+ _mxht_emit() {
30
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
31
+ MXHT_DONE=1
32
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
33
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
34
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
35
+ [ -n "$root" ] && [ -d "$root" ] || return 0
36
+ local dir="$root/.mx-hook-timing"
37
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
38
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
39
+ # strip both forms and subtract as plain integer microseconds.
40
+ local dur=-1
41
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
42
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
43
+ local stamp hour
44
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
45
+ printf -v hour '%(%H)T' -1
46
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
47
+ # is at most 24 files each holding one hour of this machine's hook calls. The
48
+ # first writer into a slot on a new day truncates it instead of appending —
49
+ # detected by reading the slot's first line, which is a builtin read (no stat,
50
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
51
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
52
+ local f="$dir/h$hour.log" first="" line
53
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
54
+ # Anything else is a silent no-op. Two concrete failures if this check is
55
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
56
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
57
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
58
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
59
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
60
+ # dangling symlink, so -L is needed to catch that case too).
61
+ if [ -e "$f" ] || [ -L "$f" ]; then
62
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
63
+ fi
64
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
65
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
66
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
67
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
68
+ # concurrent hooks cannot interleave partial lines.
69
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
70
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
71
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
72
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
73
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
74
+ else
75
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
76
+ fi
77
+ }
78
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
79
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
80
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
81
+ # final printf failing on an unwritable slot is the reachable case — replaces the
82
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
83
+ # harness reads as "error", not "block", so the command it meant to block runs.
84
+ # Pinned verbatim by hook-timing-parity.test.sh.
85
+ trap '_mxht_emit || :' EXIT
86
+ # <<< SHARED hook-timing probe v1
87
+
88
+
10
89
  # Fail-open: any error → exit 0 silently
11
90
  trap 'exit 0' ERR
12
91
  set -u
@@ -55,6 +55,85 @@
55
55
  # here is one confusing gh failure, not lost work, and matching the whole
56
56
  # command loosely instead of anchoring per segment is its own defect (#4804).
57
57
 
58
+ MXHT_HOOK=gh-pr-edit-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
59
+ # >>> SHARED hook-timing probe v1
60
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
61
+ # separated from time spent waiting on the API when a session stalls mid-stream.
62
+ # Appends one line to a local, gitignored log. Read it with
63
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
64
+ #
65
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
66
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
67
+ # default. A diagnostic that can break the gate it observes is worse than no
68
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
69
+ # guard on the PreToolUse path at once. Every step below is guarded and every
70
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
71
+ #
72
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
73
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
74
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
75
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
76
+ MXHT_T0="${EPOCHREALTIME:-}"
77
+ _mxht_emit() {
78
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
79
+ MXHT_DONE=1
80
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
81
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
82
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
83
+ [ -n "$root" ] && [ -d "$root" ] || return 0
84
+ local dir="$root/.mx-hook-timing"
85
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
86
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
87
+ # strip both forms and subtract as plain integer microseconds.
88
+ local dur=-1
89
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
90
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
91
+ local stamp hour
92
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
93
+ printf -v hour '%(%H)T' -1
94
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
95
+ # is at most 24 files each holding one hour of this machine's hook calls. The
96
+ # first writer into a slot on a new day truncates it instead of appending —
97
+ # detected by reading the slot's first line, which is a builtin read (no stat,
98
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
99
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
100
+ local f="$dir/h$hour.log" first="" line
101
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
102
+ # Anything else is a silent no-op. Two concrete failures if this check is
103
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
104
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
105
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
106
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
107
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
108
+ # dangling symlink, so -L is needed to catch that case too).
109
+ if [ -e "$f" ] || [ -L "$f" ]; then
110
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
111
+ fi
112
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
113
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
114
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
115
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
116
+ # concurrent hooks cannot interleave partial lines.
117
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
118
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
119
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
120
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
121
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
122
+ else
123
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
124
+ fi
125
+ }
126
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
127
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
128
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
129
+ # final printf failing on an unwritable slot is the reachable case — replaces the
130
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
131
+ # harness reads as "error", not "block", so the command it meant to block runs.
132
+ # Pinned verbatim by hook-timing-parity.test.sh.
133
+ trap '_mxht_emit || :' EXIT
134
+ # <<< SHARED hook-timing probe v1
135
+
136
+
58
137
  set -uo pipefail
59
138
 
60
139
  # Read stdin with the bash redirection builtin rather than `cat`. A hook whose
@@ -77,6 +77,85 @@
77
77
  # match. The guard deters accidental discards; it does not stop a determined
78
78
  # caller.
79
79
 
80
+ MXHT_HOOK=git-mutation-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
81
+ # >>> SHARED hook-timing probe v1
82
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
83
+ # separated from time spent waiting on the API when a session stalls mid-stream.
84
+ # Appends one line to a local, gitignored log. Read it with
85
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
86
+ #
87
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
88
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
89
+ # default. A diagnostic that can break the gate it observes is worse than no
90
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
91
+ # guard on the PreToolUse path at once. Every step below is guarded and every
92
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
93
+ #
94
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
95
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
96
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
97
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
98
+ MXHT_T0="${EPOCHREALTIME:-}"
99
+ _mxht_emit() {
100
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
101
+ MXHT_DONE=1
102
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
103
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
104
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
105
+ [ -n "$root" ] && [ -d "$root" ] || return 0
106
+ local dir="$root/.mx-hook-timing"
107
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
108
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
109
+ # strip both forms and subtract as plain integer microseconds.
110
+ local dur=-1
111
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
112
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
113
+ local stamp hour
114
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
115
+ printf -v hour '%(%H)T' -1
116
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
117
+ # is at most 24 files each holding one hour of this machine's hook calls. The
118
+ # first writer into a slot on a new day truncates it instead of appending —
119
+ # detected by reading the slot's first line, which is a builtin read (no stat,
120
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
121
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
122
+ local f="$dir/h$hour.log" first="" line
123
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
124
+ # Anything else is a silent no-op. Two concrete failures if this check is
125
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
126
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
127
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
128
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
129
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
130
+ # dangling symlink, so -L is needed to catch that case too).
131
+ if [ -e "$f" ] || [ -L "$f" ]; then
132
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
133
+ fi
134
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
135
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
136
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
137
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
138
+ # concurrent hooks cannot interleave partial lines.
139
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
140
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
141
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
142
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
143
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
144
+ else
145
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
146
+ fi
147
+ }
148
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
149
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
150
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
151
+ # final printf failing on an unwritable slot is the reachable case — replaces the
152
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
153
+ # harness reads as "error", not "block", so the command it meant to block runs.
154
+ # Pinned verbatim by hook-timing-parity.test.sh.
155
+ trap '_mxht_emit || :' EXIT
156
+ # <<< SHARED hook-timing probe v1
157
+
158
+
80
159
  set -euo pipefail
81
160
 
82
161
  INPUT=$(cat)