@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.
@@ -14,6 +14,85 @@
14
14
  # mechanism used by auto-capture-session-end.sh), reads the iteration log via
15
15
  # the mx CLI, and compares timestamps.
16
16
 
17
+ MXHT_HOOK=iteration-log-check MXHT_EVENT=Stop MXHT_TOOL=-
18
+ # >>> SHARED hook-timing probe v1
19
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
20
+ # separated from time spent waiting on the API when a session stalls mid-stream.
21
+ # Appends one line to a local, gitignored log. Read it with
22
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
23
+ #
24
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
25
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
26
+ # default. A diagnostic that can break the gate it observes is worse than no
27
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
28
+ # guard on the PreToolUse path at once. Every step below is guarded and every
29
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
30
+ #
31
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
32
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
33
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
34
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
35
+ MXHT_T0="${EPOCHREALTIME:-}"
36
+ _mxht_emit() {
37
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
38
+ MXHT_DONE=1
39
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
40
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
41
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
42
+ [ -n "$root" ] && [ -d "$root" ] || return 0
43
+ local dir="$root/.mx-hook-timing"
44
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
45
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
46
+ # strip both forms and subtract as plain integer microseconds.
47
+ local dur=-1
48
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
49
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
50
+ local stamp hour
51
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
52
+ printf -v hour '%(%H)T' -1
53
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
54
+ # is at most 24 files each holding one hour of this machine's hook calls. The
55
+ # first writer into a slot on a new day truncates it instead of appending —
56
+ # detected by reading the slot's first line, which is a builtin read (no stat,
57
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
58
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
59
+ local f="$dir/h$hour.log" first="" line
60
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
61
+ # Anything else is a silent no-op. Two concrete failures if this check is
62
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
63
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
64
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
65
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
66
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
67
+ # dangling symlink, so -L is needed to catch that case too).
68
+ if [ -e "$f" ] || [ -L "$f" ]; then
69
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
70
+ fi
71
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
72
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
73
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
74
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
75
+ # concurrent hooks cannot interleave partial lines.
76
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
77
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
78
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
79
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
80
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
81
+ else
82
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
83
+ fi
84
+ }
85
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
86
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
87
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
88
+ # final printf failing on an unwritable slot is the reachable case — replaces the
89
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
90
+ # harness reads as "error", not "block", so the command it meant to block runs.
91
+ # Pinned verbatim by hook-timing-parity.test.sh.
92
+ trap '_mxht_emit || :' EXIT
93
+ # <<< SHARED hook-timing probe v1
94
+
95
+
17
96
  # Fail-open: any unexpected error → exit 0 silently
18
97
  trap 'exit 0' ERR
19
98
  set -u
@@ -71,6 +71,85 @@
71
71
  # as capable, not as read-only, so a broken jq degrades to the demand rather than
72
72
  # turning the gate off (see PAYLOAD_OPAQUE below).
73
73
 
74
+ MXHT_HOOK=memory-checkpoint-reminder MXHT_EVENT=PreToolUse MXHT_TOOL=-
75
+ # >>> SHARED hook-timing probe v1
76
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
77
+ # separated from time spent waiting on the API when a session stalls mid-stream.
78
+ # Appends one line to a local, gitignored log. Read it with
79
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
80
+ #
81
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
82
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
83
+ # default. A diagnostic that can break the gate it observes is worse than no
84
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
85
+ # guard on the PreToolUse path at once. Every step below is guarded and every
86
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
87
+ #
88
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
89
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
90
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
91
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
92
+ MXHT_T0="${EPOCHREALTIME:-}"
93
+ _mxht_emit() {
94
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
95
+ MXHT_DONE=1
96
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
97
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
98
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
99
+ [ -n "$root" ] && [ -d "$root" ] || return 0
100
+ local dir="$root/.mx-hook-timing"
101
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
102
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
103
+ # strip both forms and subtract as plain integer microseconds.
104
+ local dur=-1
105
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
106
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
107
+ local stamp hour
108
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
109
+ printf -v hour '%(%H)T' -1
110
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
111
+ # is at most 24 files each holding one hour of this machine's hook calls. The
112
+ # first writer into a slot on a new day truncates it instead of appending —
113
+ # detected by reading the slot's first line, which is a builtin read (no stat,
114
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
115
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
116
+ local f="$dir/h$hour.log" first="" line
117
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
118
+ # Anything else is a silent no-op. Two concrete failures if this check is
119
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
120
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
121
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
122
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
123
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
124
+ # dangling symlink, so -L is needed to catch that case too).
125
+ if [ -e "$f" ] || [ -L "$f" ]; then
126
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
127
+ fi
128
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
129
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
130
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
131
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
132
+ # concurrent hooks cannot interleave partial lines.
133
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
134
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
135
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
136
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
137
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
138
+ else
139
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
140
+ fi
141
+ }
142
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
143
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
144
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
145
+ # final printf failing on an unwritable slot is the reachable case — replaces the
146
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
147
+ # harness reads as "error", not "block", so the command it meant to block runs.
148
+ # Pinned verbatim by hook-timing-parity.test.sh.
149
+ trap '_mxht_emit || :' EXIT
150
+ # <<< SHARED hook-timing probe v1
151
+
152
+
74
153
  # Fail-open: any error → exit 0 silently
75
154
  trap 'exit 0' ERR
76
155
  set -u
@@ -38,6 +38,83 @@
38
38
  # `git -C /treeA push && git -C /treeB push` pushed unlinted. Every push
39
39
  # segment is now resolved and every distinct toplevel linted.
40
40
 
41
+ MXHT_HOOK=mx-guard-hook MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
42
+ # >>> SHARED hook-timing probe v1
43
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
44
+ # separated from time spent waiting on the API when a session stalls mid-stream.
45
+ # Appends one line to a local, gitignored log. Read it with
46
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
47
+ #
48
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
49
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
50
+ # default. A diagnostic that can break the gate it observes is worse than no
51
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
52
+ # guard on the PreToolUse path at once. Every step below is guarded and every
53
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
54
+ #
55
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
56
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
57
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
58
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
59
+ MXHT_T0="${EPOCHREALTIME:-}"
60
+ _mxht_emit() {
61
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
62
+ MXHT_DONE=1
63
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
64
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
65
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
66
+ [ -n "$root" ] && [ -d "$root" ] || return 0
67
+ local dir="$root/.mx-hook-timing"
68
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
69
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
70
+ # strip both forms and subtract as plain integer microseconds.
71
+ local dur=-1
72
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
73
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
74
+ local stamp hour
75
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
76
+ printf -v hour '%(%H)T' -1
77
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
78
+ # is at most 24 files each holding one hour of this machine's hook calls. The
79
+ # first writer into a slot on a new day truncates it instead of appending —
80
+ # detected by reading the slot's first line, which is a builtin read (no stat,
81
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
82
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
83
+ local f="$dir/h$hour.log" first="" line
84
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
85
+ # Anything else is a silent no-op. Two concrete failures if this check is
86
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
87
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
88
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
89
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
90
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
91
+ # dangling symlink, so -L is needed to catch that case too).
92
+ if [ -e "$f" ] || [ -L "$f" ]; then
93
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
94
+ fi
95
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
96
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
97
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
98
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
99
+ # concurrent hooks cannot interleave partial lines.
100
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
101
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
102
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
103
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
104
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
105
+ else
106
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
107
+ fi
108
+ }
109
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
110
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
111
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
112
+ # final printf failing on an unwritable slot is the reachable case — replaces the
113
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
114
+ # harness reads as "error", not "block", so the command it meant to block runs.
115
+ # Pinned verbatim by hook-timing-parity.test.sh.
116
+ trap '_mxht_emit || :' EXIT
117
+ # <<< SHARED hook-timing probe v1
41
118
 
42
119
 
43
120
  # Read hook input from stdin
@@ -39,6 +39,85 @@
39
39
  # refuse()->stderr+exit2, fail-open), iteration-log-check.sh (best-effort
40
40
  # emit_telemetry with the MX_HOOK_TELEMETRY kill-switch and mx-on-PATH guard).
41
41
 
42
+ MXHT_HOOK=named-memory-write-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
43
+ # >>> SHARED hook-timing probe v1
44
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
45
+ # separated from time spent waiting on the API when a session stalls mid-stream.
46
+ # Appends one line to a local, gitignored log. Read it with
47
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
48
+ #
49
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
50
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
51
+ # default. A diagnostic that can break the gate it observes is worse than no
52
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
53
+ # guard on the PreToolUse path at once. Every step below is guarded and every
54
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
55
+ #
56
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
57
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
58
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
59
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
60
+ MXHT_T0="${EPOCHREALTIME:-}"
61
+ _mxht_emit() {
62
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
63
+ MXHT_DONE=1
64
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
65
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
66
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
67
+ [ -n "$root" ] && [ -d "$root" ] || return 0
68
+ local dir="$root/.mx-hook-timing"
69
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
70
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
71
+ # strip both forms and subtract as plain integer microseconds.
72
+ local dur=-1
73
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
74
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
75
+ local stamp hour
76
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
77
+ printf -v hour '%(%H)T' -1
78
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
79
+ # is at most 24 files each holding one hour of this machine's hook calls. The
80
+ # first writer into a slot on a new day truncates it instead of appending —
81
+ # detected by reading the slot's first line, which is a builtin read (no stat,
82
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
83
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
84
+ local f="$dir/h$hour.log" first="" line
85
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
86
+ # Anything else is a silent no-op. Two concrete failures if this check is
87
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
88
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
89
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
90
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
91
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
92
+ # dangling symlink, so -L is needed to catch that case too).
93
+ if [ -e "$f" ] || [ -L "$f" ]; then
94
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
95
+ fi
96
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
97
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
98
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
99
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
100
+ # concurrent hooks cannot interleave partial lines.
101
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
102
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
103
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
104
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
105
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
106
+ else
107
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
108
+ fi
109
+ }
110
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
111
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
112
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
113
+ # final printf failing on an unwritable slot is the reachable case — replaces the
114
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
115
+ # harness reads as "error", not "block", so the command it meant to block runs.
116
+ # Pinned verbatim by hook-timing-parity.test.sh.
117
+ trap '_mxht_emit || :' EXIT
118
+ # <<< SHARED hook-timing probe v1
119
+
120
+
42
121
  set -euo pipefail
43
122
 
44
123
  # ── Config ───────────────────────────────────────────────────────────────────
@@ -3,6 +3,83 @@
3
3
  # Logs sync failures to the local startup JSONL so they are visible at next session start.
4
4
  # FAIL-OPEN: always exits 0 regardless of sync outcome.
5
5
 
6
+ MXHT_HOOK=observability-sync MXHT_EVENT=Stop MXHT_TOOL=-
7
+ # >>> SHARED hook-timing probe v1
8
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
9
+ # separated from time spent waiting on the API when a session stalls mid-stream.
10
+ # Appends one line to a local, gitignored log. Read it with
11
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
12
+ #
13
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
14
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
15
+ # default. A diagnostic that can break the gate it observes is worse than no
16
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
17
+ # guard on the PreToolUse path at once. Every step below is guarded and every
18
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
19
+ #
20
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
21
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
22
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
23
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
24
+ MXHT_T0="${EPOCHREALTIME:-}"
25
+ _mxht_emit() {
26
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
27
+ MXHT_DONE=1
28
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
29
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
30
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
31
+ [ -n "$root" ] && [ -d "$root" ] || return 0
32
+ local dir="$root/.mx-hook-timing"
33
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
34
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
35
+ # strip both forms and subtract as plain integer microseconds.
36
+ local dur=-1
37
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
38
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
39
+ local stamp hour
40
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
41
+ printf -v hour '%(%H)T' -1
42
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
43
+ # is at most 24 files each holding one hour of this machine's hook calls. The
44
+ # first writer into a slot on a new day truncates it instead of appending —
45
+ # detected by reading the slot's first line, which is a builtin read (no stat,
46
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
47
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
48
+ local f="$dir/h$hour.log" first="" line
49
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
50
+ # Anything else is a silent no-op. Two concrete failures if this check is
51
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
52
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
53
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
54
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
55
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
56
+ # dangling symlink, so -L is needed to catch that case too).
57
+ if [ -e "$f" ] || [ -L "$f" ]; then
58
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
59
+ fi
60
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
61
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
62
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
63
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
64
+ # concurrent hooks cannot interleave partial lines.
65
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
66
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
67
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
68
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
69
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
70
+ else
71
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
72
+ fi
73
+ }
74
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
75
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
76
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
77
+ # final printf failing on an unwritable slot is the reachable case — replaces the
78
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
79
+ # harness reads as "error", not "block", so the command it meant to block runs.
80
+ # Pinned verbatim by hook-timing-parity.test.sh.
81
+ trap '_mxht_emit || :' EXIT
82
+ # <<< SHARED hook-timing probe v1
6
83
 
7
84
 
8
85
  set -euo pipefail
@@ -46,6 +46,85 @@
46
46
  # by the party it guards. Precedent: 6f934aaee removed the same affordance from
47
47
  # the override audit log.
48
48
 
49
+ MXHT_HOOK=session-idle-gate MXHT_EVENT=Stop MXHT_TOOL=-
50
+ # >>> SHARED hook-timing probe v1
51
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
52
+ # separated from time spent waiting on the API when a session stalls mid-stream.
53
+ # Appends one line to a local, gitignored log. Read it with
54
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
55
+ #
56
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
57
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
58
+ # default. A diagnostic that can break the gate it observes is worse than no
59
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
60
+ # guard on the PreToolUse path at once. Every step below is guarded and every
61
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
62
+ #
63
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
64
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
65
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
66
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
67
+ MXHT_T0="${EPOCHREALTIME:-}"
68
+ _mxht_emit() {
69
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
70
+ MXHT_DONE=1
71
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
72
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
73
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
74
+ [ -n "$root" ] && [ -d "$root" ] || return 0
75
+ local dir="$root/.mx-hook-timing"
76
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
77
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
78
+ # strip both forms and subtract as plain integer microseconds.
79
+ local dur=-1
80
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
81
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
82
+ local stamp hour
83
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
84
+ printf -v hour '%(%H)T' -1
85
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
86
+ # is at most 24 files each holding one hour of this machine's hook calls. The
87
+ # first writer into a slot on a new day truncates it instead of appending —
88
+ # detected by reading the slot's first line, which is a builtin read (no stat,
89
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
90
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
91
+ local f="$dir/h$hour.log" first="" line
92
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
93
+ # Anything else is a silent no-op. Two concrete failures if this check is
94
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
95
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
96
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
97
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
98
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
99
+ # dangling symlink, so -L is needed to catch that case too).
100
+ if [ -e "$f" ] || [ -L "$f" ]; then
101
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
102
+ fi
103
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
104
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
105
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
106
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
107
+ # concurrent hooks cannot interleave partial lines.
108
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
109
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
110
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
111
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
112
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
113
+ else
114
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
115
+ fi
116
+ }
117
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
118
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
119
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
120
+ # final printf failing on an unwritable slot is the reachable case — replaces the
121
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
122
+ # harness reads as "error", not "block", so the command it meant to block runs.
123
+ # Pinned verbatim by hook-timing-parity.test.sh.
124
+ trap '_mxht_emit || :' EXIT
125
+ # <<< SHARED hook-timing probe v1
126
+
127
+
49
128
  trap 'exit 0' ERR
50
129
  set -u
51
130
 
@@ -21,6 +21,83 @@
21
21
  # 0 = allow
22
22
  # 2 = block (path filters explain why CI didn't trigger — dispatch not needed)
23
23
 
24
+ MXHT_HOOK=workflow-dispatch-guard MXHT_EVENT=PreToolUse MXHT_TOOL=Bash
25
+ # >>> SHARED hook-timing probe v1
26
+ # Diagnostic instrumentation: records how long THIS hook ran, so hook time can be
27
+ # separated from time spent waiting on the API when a session stalls mid-stream.
28
+ # Appends one line to a local, gitignored log. Read it with
29
+ # mx-agent-system/scripts/hook-timing-report.sh. Nothing is transmitted anywhere.
30
+ #
31
+ # FAIL SILENT IS DELIBERATE HERE, and it is the opposite of this repo's usual
32
+ # fail-loud direction. Do not "correct" it to fail-loud by applying the fleet
33
+ # default. A diagnostic that can break the gate it observes is worse than no
34
+ # diagnostic: an unwritable path or a full disk would otherwise take out every
35
+ # guard on the PreToolUse path at once. Every step below is guarded and every
36
+ # failure path is a silent no-op that leaves the hook's behaviour untouched.
37
+ #
38
+ # NEAR-ZERO OVERHEAD: bash builtins only on the hot path ($EPOCHREALTIME, printf
39
+ # -T, one read, one append). No subprocess, no network, no JSON parsing, and the
40
+ # hook's stdin is never touched (the hook owns it). mkdir runs at most once per
41
+ # worktree. Kill switch: MX_HOOK_TIMING=0.
42
+ MXHT_T0="${EPOCHREALTIME:-}"
43
+ _mxht_emit() {
44
+ [ -z "${MXHT_DONE:-}" ] || return 0 # an ERR trap that exits fires EXIT too
45
+ MXHT_DONE=1
46
+ [ "${MX_HOOK_TIMING:-1}" != "0" ] || return 0
47
+ [ -n "${MXHT_T0:-}" ] && [ -n "${EPOCHREALTIME:-}" ] || return 0
48
+ local root="${CLAUDE_PROJECT_DIR:-${CLAUDE_WORKTREE_PATH:-}}"
49
+ [ -n "$root" ] && [ -d "$root" ] || return 0
50
+ local dir="$root/.mx-hook-timing"
51
+ [ -d "$dir" ] || mkdir -p "$dir" 2>/dev/null || return 0
52
+ # EPOCHREALTIME is seconds.microseconds; the separator is locale-dependent, so
53
+ # strip both forms and subtract as plain integer microseconds.
54
+ local dur=-1
55
+ { dur=$(( ${EPOCHREALTIME//[.,]/} - ${MXHT_T0//[.,]/} )); } 2>/dev/null
56
+ [ "$dur" -ge 0 ] 2>/dev/null || return 0
57
+ local stamp hour
58
+ printf -v stamp '%(%Y-%m-%d %H:%M:%S)T' -1
59
+ printf -v hour '%(%H)T' -1
60
+ # BOUNDED BY CONSTRUCTION: a 24-slot ring, one file per hour-of-day, so the log
61
+ # is at most 24 files each holding one hour of this machine's hook calls. The
62
+ # first writer into a slot on a new day truncates it instead of appending —
63
+ # detected by reading the slot's first line, which is a builtin read (no stat,
64
+ # no rm, no find, no cron). Two writers can race that truncation and lose a
65
+ # line or two at an hour boundary; that is acceptable for a sampling diagnostic.
66
+ local f="$dir/h$hour.log" first="" line
67
+ # THE SLOT MUST BE AN ORDINARY FILE, OR NOT EXIST YET (security review, #4848).
68
+ # Anything else is a silent no-op. Two concrete failures if this check is
69
+ # dropped: a FIFO at the slot makes the `read` below block until the hook's
70
+ # settings.json timeout kills it, and a PreToolUse guard killed that way loses
71
+ # its exit 2 — the command it meant to block then runs; a symlink at the slot
72
+ # sends the day-rollover truncation onto the symlink's target. The `-e || -L`
73
+ # wrapper is what lets a not-yet-created slot through (-e is false for a
74
+ # dangling symlink, so -L is needed to catch that case too).
75
+ if [ -e "$f" ] || [ -L "$f" ]; then
76
+ [ -f "$f" ] && [ ! -L "$f" ] || return 0
77
+ fi
78
+ [ -r "$f" ] && { read -r first < "$f"; } 2>/dev/null
79
+ printf -v line '%s dur_us=%s hook=%s event=%s ppid=%s tool=%s\n' \
80
+ "$stamp" "$dur" "${MXHT_HOOK:--}" "${MXHT_EVENT:--}" "$PPID" "${MXHT_TOOL:--}"
81
+ # One printf of ~90 bytes to an O_APPEND fd is atomic under PIPE_BUF, so
82
+ # concurrent hooks cannot interleave partial lines.
83
+ # The 2>/dev/null wraps the GROUP, not the printf: a failing redirection is
84
+ # reported by the shell before an inner 2>/dev/null would be in effect, and a
85
+ # "Permission denied" on stderr from a PreToolUse hook is surfaced to the model.
86
+ if [ "${first%% *}" = "${stamp%% *}" ]; then
87
+ { printf '%s' "$line" >>"$f"; } 2>/dev/null
88
+ else
89
+ { printf '%s' "$line" >"$f"; } 2>/dev/null
90
+ fi
91
+ }
92
+ # `|| :` IS LOAD-BEARING — do not simplify to `trap _mxht_emit EXIT`. The hooks
93
+ # this block is inlined into run under `set -e`, and the EXIT trap runs with
94
+ # errexit still in force. Without `|| :`, a non-zero return from the probe — the
95
+ # final printf failing on an unwritable slot is the reachable case — replaces the
96
+ # hook's own exit status: a PreToolUse guard's exit 2 becomes exit 1, which the
97
+ # harness reads as "error", not "block", so the command it meant to block runs.
98
+ # Pinned verbatim by hook-timing-parity.test.sh.
99
+ trap '_mxht_emit || :' EXIT
100
+ # <<< SHARED hook-timing probe v1
24
101
 
25
102
 
26
103
  # Fail-open: any unexpected error → allow the command through