@memnexus-ai/mx-agent-cli 0.1.166 → 0.1.167

package/dist/agent-config/hooks/memory-checkpoint-reminder.sh

@@ -0,0 +1,103 @@
+#!/bin/bash
+# memory-checkpoint-reminder.sh — PreToolUse hook (all tools)
+# Reminds agents to save a memory checkpoint when 50+ tool calls
+# have occurred since the last memory save.
+#
+# Fires on: PreToolUse (empty matcher — all tool calls)
+# Input: JSON on stdin with tool_name and tool_input
+# Output: reminder message to stdout when counter >= 50 (non-blocking)
+# Exit: always 0 (never blocks tool calls)
+
+# Fail-open: any error → exit 0 silently
+trap 'exit 0' ERR
+set -u
+
+# Save the real stderr to fd 3 up front. Section 2 opens the advisory lock with
+# `exec 200>"$LOCK_FILE" 2>/dev/null`, and bash applies that `2>/dev/null` to the
+# whole shell — permanently redirecting fd 2 to /dev/null. The threshold reminder
+# below therefore writes to fd 3 (the preserved real stderr) so the harness can
+# surface it (KI-HOOKS-STDERR-SYSTEMIC). Fail-open if fd 3 can't be opened.
+exec 3>&2 || true
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
+
+WORKTREE_NAME="${CLAUDE_WORKTREE_NAME:-default}"
+# Sanitize: alphanumeric, hyphens, underscores only — prevent path traversal
+WORKTREE_NAME="${WORKTREE_NAME//[^a-zA-Z0-9_-]/}"
+WORKTREE_NAME="${WORKTREE_NAME:-default}"
+COUNTER_FILE="/tmp/.mx-checkpoint-counter-${WORKTREE_NAME}"
+THRESHOLD=50
+
+# Reset counter if it's stale (from a previous session — >30 min old)
+if [[ -f "$COUNTER_FILE" ]]; then
+  MTIME=$(stat -c %Y "$COUNTER_FILE" 2>/dev/null || stat -f %m "$COUNTER_FILE" 2>/dev/null || echo "0")
+  NOW=$(date +%s)
+  AGE=$((NOW - MTIME))
+  if [[ "$AGE" -gt 1800 ]]; then
+    echo "0" > "$COUNTER_FILE" 2>/dev/null || true
+  fi
+fi
+
+# ── 1. Detect memory save operations ────────────────────────────────────────
+# Reset counter if this tool call IS a memory save:
+# - MCP tools: mcp__memnexus__create_memory, mcp__memnexus__manage_memory
+#   (also handle mcp__MX__ prefix used in some environments)
+# - Bash tool: command contains "mx memories create" or "mx memories update"
+
+IS_MEMORY_SAVE=0
+
+if [[ "$TOOL_NAME" == *"create_memory"* || "$TOOL_NAME" == *"manage_memory"* ]]; then
+  IS_MEMORY_SAVE=1
+fi
+
+if [[ "$TOOL_NAME" == "Bash" ]]; then
+  COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty' 2>/dev/null)
+  if [[ "$COMMAND" == *"mx memories create"* || "$COMMAND" == *"mx memories update"* ]]; then
+    IS_MEMORY_SAVE=1
+  fi
+fi
+
+if [[ "$IS_MEMORY_SAVE" -eq 1 ]]; then
+  # Reset counter — memory was just saved
+  echo "0" > "$COUNTER_FILE" 2>/dev/null || true
+  exit 0
+fi
+
+# ── 2. Increment counter (use flock for atomic operation if available) ────────
+LOCK_FILE="${COUNTER_FILE}.lock"
+CURRENT=0
+
+if command -v flock >/dev/null 2>&1; then
+  exec 200>"$LOCK_FILE" 2>/dev/null
+  flock -x 200 2>/dev/null || true
+fi
+
+if [[ -f "$COUNTER_FILE" ]]; then
+  CURRENT=$(cat "$COUNTER_FILE" 2>/dev/null || echo "0")
+  [[ "$CURRENT" =~ ^[0-9]+$ ]] || CURRENT=0
+fi
+
+CURRENT=$((CURRENT + 1))
+echo "$CURRENT" > "$COUNTER_FILE" 2>/dev/null || true
+
+# ── 3. Emit reminder if threshold reached ────────────────────────────────────
+if [[ "$CURRENT" -ge "$THRESHOLD" ]]; then
+  # Reset counter — after save + retry, next 50 calls proceed unblocked
+  echo "0" > "$COUNTER_FILE" 2>/dev/null || true
+
+  # Route to the preserved real stderr (fd 3) — exit-2 PreToolUse messages
+  # surface via stderr, not stdout (KI-HOOKS-STDERR-SYSTEMIC). fd 2 may have been
+  # redirected to /dev/null by the flock exec above, so fd 3 is used here.
+  {
+    echo ""
+    echo "⚠️  Memory checkpoint required: ${CURRENT} tool calls since last memory save."
+    echo "1. Save a checkpoint now (required before continuing):"
+    echo "  mx memories create --conversation-id \"<conv_id>\" --content \"[what you've done]. Next: [next step].\" --topics \"<component>,in-progress\""
+    echo "2. After saving, retry your original tool call."
+    echo ""
+  } >&3
+  exit 2  # Surface this message to the agent — exit 2 is required for PreToolUse visibility
+fi
+
+exit 0

package/dist/agent-config/hooks/mx-guard-hook.sh

@@ -0,0 +1,77 @@
+#!/bin/bash
+# mx-guard pre-push enforcement hook
+# Runs mx-guard check before allowing git push commands.
+# Deployed by mx-agent create via syncClaudeConfig().
+#
+# Exit codes:
+#   0 = allow (not a push command, or mx-guard passes)
+#   2 = block (mx-guard found errors)
+
+# Read hook input from stdin
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
+
+# Cheap literal pre-filter (ported from ci-validate-hook.sh, #3731): bail before
+# the regex on any command that can't contain "push". Keeps the pattern match
+# off the hot path for the vast majority of commands.
+case "$COMMAND" in
+  *push*) ;;
+  *) exit 0 ;;
+esac
+
+# Segment-aware push matcher (H1, ported from ci-validate-hook.sh #3731; SF-3).
+# The old `^git\ push` matcher was start-anchored, so compound commands
+# (cd $CLAUDE_WORKTREE_PATH/<pkg> && git push) and other routine forms bypassed
+# validation entirely. Match "git push" when it BEGINS a command segment.
+# Segment starts: start-of-command (^); a separator ; & | { ( or a control char
+# (newline/tab — [:cntrl:] matches newline but NOT space); a shell keyword
+# then/do/else. SF-3 added `(` to the start class and `)` to the trailing group
+# so the subshell form (git push) matches and closes correctly. Also tolerated
+# before git: leading redirections (`2>/dev/null `), env-var assignments
+# (VAR=1 git push), and launcher/wrapper words (sudo/env/nice/nohup/time/
+# timeout/ionice/stdbuf/command/xargs/setsid, optional numeric arg) so
+# wrapper-prefixed pushes aren't skipped. GIT GLOBAL OPTIONS between `git` and
+# `push` are consumed (High, #3934): `-C <path>`, `-c <k>=<v>`,
+# `--git-dir[=| ]<p>`, `--work-tree[=| ]<p>`, `--namespace[=| ]<p>`,
+# `--no-pager`, and generic single/double-dash forms with or without values.
+# Pre-#3934 only `-C <path>` was consumed, so `git --no-pager push` and
+# `git -c core.sshCommand=x push` skipped validation. Kept consistent with
+# git-mutation-guard GITSEG.
+PUSH_RE='(^|[;&|{([:cntrl:]]|[[:space:]](then|do|else)[[:space:]])[[:space:]]*([0-9]*[<>][^[:space:]]*[[:space:]]+|[A-Za-z_][A-Za-z0-9_]*=[^[:space:];&|]*[[:space:]]+|(sudo|env|nice|nohup|time|timeout|ionice|stdbuf|command|xargs|setsid)[[:space:]]+([0-9]+[[:space:]]+)?)*git([[:space:]]+(-C[[:space:]]+[^[:space:];&|]+|-c[[:space:]]+[^[:space:];&|]+|--(git-dir|work-tree|namespace|super-prefix)(=[^[:space:];&|]*|[[:space:]]+[^[:space:];&|]+)|--[A-Za-z][A-Za-z0-9-]*=[^[:space:];&|]*|--[A-Za-z][A-Za-z0-9-]*|-[A-Za-z]))*[[:space:]]+push([[:space:]]|[;&|)]|$)'
+if [[ ! "$COMMAND" =~ $PUSH_RE ]]; then
+  exit 0
+fi
+
+# All hook-authored messages go to stderr — the harness surfaces a blocking
+# hook's stderr, not its stdout (KI-HOOKS-STDERR-SYSTEMIC).
+
+# Check if mx-guard is available
+if ! command -v mx-guard &>/dev/null; then
+  {
+    echo "⚠ mx-guard not installed — skipping pre-push validation"
+    echo "  Install: pnpm install -g @memnexus-ai/mx-guard"
+  } >&2
+  exit 0
+fi
+
+# Run mx-guard check (change-aware — only checks files on current branch).
+# Route its output to stderr so its findings are visible on the block path.
+{
+  echo "Running mx-guard check before push..."
+  echo ""
+} >&2
+
+mx-guard check >&2
+GUARD_EXIT=$?
+
+if [ $GUARD_EXIT -ne 0 ]; then
+  {
+    echo ""
+    echo "mx-guard: push blocked. Fix the errors above before pushing."
+    echo "  To check specific rules: mx-guard check --rule <category>"
+    echo "  To see all rules: mx-guard rules"
+  } >&2
+  exit 2
+fi
+
+exit 0

package/dist/agent-config/hooks/named-memory-write-guard.sh

@@ -0,0 +1,237 @@
+#!/bin/bash
+# named-memory-write-guard — PreToolUse(Bash) guard against TRUNCATING full-content
+# writes to NAMED MemNexus memories.
+#
+# Contract: reads the tool-call JSON on stdin, extracts .tool_input.command.
+#   exit 0 = allow, exit 2 = block (non-zero exit blocks the Bash command).
+# Fails OPEN (exit 0) on any parse ambiguity, missing tool, fetch failure, or
+# timeout — it never wedges legitimate work.
+#
+# OUTPUT ROUTING (KI-HOOKS-STDERR-SYSTEMIC, 2026-07-04): the harness surfaces a
+# blocking hook's STDERR, not its stdout, on exit 2. Every block message goes to
+# stderr (>&2). The allow paths stay silent.
+#
+# WHY: two real incidents where an agent's full-content replacement silently
+# destroyed most of a shared NAMED memory —
+#   - 2026-07-07: memnexus-<team>-known-issues dropped ~60% of its content.
+#   - 2026-07-09: memnexus-cross-team-escalations went 49,995 → 3,280 chars.
+# `mx memories update --name X --content <NEW>` REPLACES the whole document. When
+# <NEW> is much smaller than the current head, the write is almost always an
+# accidental clobber of a shared doc that should have been fetch-then-edited.
+# This guard compares the new content length against the current head and blocks
+# a shrink past a threshold unless the caller opts in.
+#
+# SCOPE — this is a length heuristic, not a content-integrity check. Truncations
+# that keep >=60% of characters, and same-length-or-longer replacements that
+# discard prior entries, are NOT caught. Server-side append/CAS (#3697) is the
+# durable fix. This is a guardrail, not a security boundary. It measures the
+# INLINE literal content on the command line. When the content is assembled via
+# shell expansion (`$(...)`, `${VAR}`, `$VAR`, backticks) its real length is
+# unknown at hook time, so the guard FAILS OPEN for that command (never a false
+# block).
+# Indirection via a script file, variable/eval assembly, or the MCP write path
+# (which is not a Bash tool call) is out of scope and NOT defended here.
+#
+# ESCAPE HATCH: set MX_SHRINK_OK=1 to allow an intentional rotation/archival that
+# genuinely shrinks a named memory (e.g. moving resolved threads to an archive).
+#
+# Precedent / conventions mirrored: git-mutation-guard.sh (stdin JSON parse,
+# refuse()->stderr+exit2, fail-open), iteration-log-check.sh (best-effort
+# emit_telemetry with the MX_HOOK_TELEMETRY kill-switch and mx-on-PATH guard).
+
+set -euo pipefail
+
+# ── Config ───────────────────────────────────────────────────────────────────
+# SHRINK_THRESHOLD: allow the write only when new_length is at least this percent
+# of the current head length. Below it (a shrink of more than 100-THRESHOLD%) the
+# write is blocked unless MX_SHRINK_OK=1. Chosen at 60 so both real incidents
+# (2026-07-07 ~60% drop, 2026-07-09 ~93% drop) are caught while normal edits —
+# which rarely remove >40% at once — pass untouched.
+SHRINK_THRESHOLD=60
+# GET_TIMEOUT: seconds to wait for the head fetch. A slow API must never stall a
+# Bash tool call; on timeout we fail open.
+GET_TIMEOUT=10
+
+# ── Recursion guard ──────────────────────────────────────────────────────────
+# The hook itself shells out to `mx memories get` (and, best-effort, `mx memories
+# create` for telemetry). Those are subprocesses, not new tool calls, so they do
+# not re-enter this hook. We still gate on MX_WRITE_GUARD_ACTIVE defensively in
+# case of any nested invocation, and we export it around our own mx calls.
+if [[ "${MX_WRITE_GUARD_ACTIVE:-}" == "1" ]]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // .command // empty' 2>/dev/null || true)
+
+# Can't parse a command — fail open.
+if [[ -z "$COMMAND" ]]; then
+  exit 0
+fi
+
+# ── Cheap non-matching fast path (no python, no network) ─────────────────────
+# This hook runs on EVERY Bash tool call. Reject the overwhelming majority of
+# commands with a few substring greps before doing any structural parse or
+# network fetch. A candidate must mention `memories`, an `update` or `create`
+# subcommand, AND carry both `--name` and `--content` (any order, `=` forms
+# included). Anything missing one of these exits 0 immediately and silently.
+if ! printf '%s' "$COMMAND" | grep -q -- 'memories'; then exit 0; fi
+if ! printf '%s' "$COMMAND" | grep -qE -- '(update|create)'; then exit 0; fi
+if ! printf '%s' "$COMMAND" | grep -q -- '--name'; then exit 0; fi
+if ! printf '%s' "$COMMAND" | grep -q -- '--content'; then exit 0; fi
+
+# Structural parse needs python3 (shlex tokenizes respecting quotes WITHOUT
+# executing anything). If it is absent, fail open — a guardrail must not block
+# work just because a helper is missing.
+if ! command -v python3 >/dev/null 2>&1; then
+  exit 0
+fi
+
+# ── Structural match + inline-content length via shlex ───────────────────────
+# PARSE is one of:
+#   "MATCH\t<name>\t<new_len>"  — a real `mx memories update|create` with both
+#                                  --name and inline literal --content.
+#   "SKIP"                       — matched shape but content is shell-expanded
+#                                  (length unknown) or quotes are unbalanced;
+#                                  fail open.
+#   "NOMATCH"                    — the greps tripped but there is no real
+#                                  update|create --name --content invocation.
+PY_PARSE='
+import sys, re, shlex
+data = sys.stdin.read()
+try:
+    toks = shlex.split(data, posix=True)
+except ValueError:
+    print("SKIP"); sys.exit(0)
+name = None; content = None; found = False
+seps = {";", "|", "||", "&&", "&", "(", ")", "{", "}"}
+i, n = 0, len(toks)
+while i < n:
+    t = toks[i]
+    if (t == "mx" or t.endswith("/mx")) and i + 2 < n and toks[i+1] == "memories" and toks[i+2] in ("update", "create"):
+        found = True
+        j = i + 3
+        while j < n:
+            a = toks[j]
+            if a in seps or a == "mx":
+                break
+            if a == "--name" and j + 1 < n:
+                name = toks[j+1]; j += 2; continue
+            if a.startswith("--name="):
+                name = a[len("--name="):]; j += 1; continue
+            if a == "--content" and j + 1 < n:
+                content = toks[j+1]; j += 2; continue
+            if a.startswith("--content="):
+                content = a[len("--content="):]; j += 1; continue
+            j += 1
+        break
+    i += 1
+if not found or not name or content is None:
+    print("NOMATCH"); sys.exit(0)
+# Content assembled via shell expansion -> real length unknown at hook time.
+# Fail open rather than risk a false block. Covers $(...), ${VAR}, $VAR, `...`.
+if re.search(r"\$[A-Za-z_{(]", content) or "`" in content:
+    print("SKIP"); sys.exit(0)
+print("MATCH\t%s\t%d" % (name, len(content)))
+'
+PARSE=$(printf '%s' "$COMMAND" | MX_WRITE_GUARD_ACTIVE=1 python3 -c "$PY_PARSE" 2>/dev/null || true)
+
+# ── Telemetry (best-effort, non-blocking) ────────────────────────────────────
+# Mirrors iteration-log-check.sh emit_telemetry: one `hook-fired:` memory per
+# decision, time-boxed, honours the MX_HOOK_TELEMETRY=0 kill-switch, no-ops when
+# mx is absent. The create carries NO --name, so it cannot re-trigger this guard
+# (the fast path requires both --name and --content); we also set
+# MX_WRITE_GUARD_ACTIVE=1 around it. Any failure here is swallowed.
+emit_telemetry() {
+  if [[ "${MX_HOOK_TELEMETRY:-1}" == "0" ]]; then return 0; fi
+  command -v mx >/dev/null 2>&1 || return 0
+  local mem="$1" old_len="$2" new_len="$3" blocked="$4" override="$5"
+  local team ts
+  team="${CLAUDE_TEAM_NAME:-}"
+  if [[ -z "$team" && -n "${CLAUDE_WORKTREE_NAME:-}" ]]; then
+    team=$(printf '%s' "$CLAUDE_WORKTREE_NAME" | sed 's/-[0-9]\{8\}$//')
+  fi
+  team="${team//[^a-zA-Z0-9-]/}"
+  team="${team:-unknown}"
+  ts=$(date -u +%Y-%m-%dT%H:%M:%SZ 2>/dev/null || echo "")
+  MX_WRITE_GUARD_ACTIVE=1 timeout 5 mx memories create \
+    --content "hook-fired: named-memory-write-guard memory=${mem} old_len=${old_len} new_len=${new_len} blocked=${blocked} override=${override} team=${team} ts=${ts}" \
+    --topics "hook-telemetry,platform" \
+    --code-context '{"product":"memnexus","team":"platform","role":"hook-telemetry"}' \
+    >/dev/null 2>&1 || true
+}
+
+# NOMATCH / SKIP / empty → allow. SKIP is the shell-expansion fail-open case; log
+# it so the fail-open rate is visible, but do not block.
+if [[ "$PARSE" != MATCH* ]]; then
+  if [[ "$PARSE" == "SKIP" ]]; then
+    emit_telemetry "unknown" "unknown" "unknown" "no" "skip-expansion"
+  fi
+  exit 0
+fi
+
+NAME=$(printf '%s' "$PARSE" | cut -f2)
+NEW_LEN=$(printf '%s' "$PARSE" | cut -f3)
+
+# ── Fetch current head ───────────────────────────────────────────────────────
+if ! command -v mx >/dev/null 2>&1; then
+  exit 0
+fi
+
+HEAD_JSON=$(MX_WRITE_GUARD_ACTIVE=1 timeout "$GET_TIMEOUT" mx memories get --name "$NAME" --format json 2>/dev/null || true)
+
+# Parse tolerantly: the CLI may print status lines before the JSON body, so read
+# from the first line containing `{` onward, then take .content length.
+HEAD_LEN=$(printf '%s' "$HEAD_JSON" | sed -n '/{/,$p' | jq -r '(.content // "") | length' 2>/dev/null || true)
+
+# Fetch failed, memory not found, timeout, or empty/zero head → FAIL OPEN, but
+# log the event so we can see how often the head is unreadable.
+if [[ -z "$HEAD_LEN" || ! "$HEAD_LEN" =~ ^[0-9]+$ || "$HEAD_LEN" -eq 0 ]]; then
+  emit_telemetry "$NAME" "fetch-fail" "$NEW_LEN" "no" "fetch-fail"
+  exit 0
+fi
+
+# ── Threshold decision (integer math) ────────────────────────────────────────
+# Allow when new_len >= SHRINK_THRESHOLD% of head_len, i.e.
+#   new_len * 100 >= SHRINK_THRESHOLD * head_len
+if (( NEW_LEN * 100 >= SHRINK_THRESHOLD * HEAD_LEN )); then
+  emit_telemetry "$NAME" "$HEAD_LEN" "$NEW_LEN" "no" "no"
+  exit 0
+fi
+
+# Below threshold: a truncating write. Honour the explicit opt-out.
+if [[ "${MX_SHRINK_OK:-}" == "1" ]]; then
+  emit_telemetry "$NAME" "$HEAD_LEN" "$NEW_LEN" "no" "yes"
+  exit 0
+fi
+
+# ── Block ────────────────────────────────────────────────────────────────────
+DROP_PCT=$(( (HEAD_LEN - NEW_LEN) * 100 / HEAD_LEN ))
+emit_telemetry "$NAME" "$HEAD_LEN" "$NEW_LEN" "yes" "no"
+{
+  echo ""
+  echo "BLOCKED: truncating write to named memory \"${NAME}\""
+  echo "This is a local guardrail (named-memory-write-guard hook), not a MemNexus"
+  echo "service error — do not file a P0."
+  echo "  head ${HEAD_LEN} chars → new ${NEW_LEN} chars (-${DROP_PCT}%)"
+  echo ""
+  echo "A full --content replacement this much smaller than the current head is"
+  echo "almost always an accidental clobber of a shared named memory (two real"
+  echo "incidents: 2026-07-07 known-issues ~60% loss, 2026-07-09 escalations"
+  echo "49,995 → 3,280 chars)."
+  echo ""
+  echo "Known sanctioned case: composer archival/rotation passes on"
+  echo "memnexus-cross-team-escalations legitimately shrink content — use the"
+  echo "inline override for those."
+  echo ""
+  echo "If this is an intentional rotation/archival, override INLINE for this one"
+  echo "command only (do NOT export MX_SHRINK_OK — that disables the guard for the"
+  echo "rest of the session). Before overriding, re-fetch the head"
+  echo "(mx memories get --name \"${NAME}\") and confirm the shrink is intentional:"
+  echo "    MX_SHRINK_OK=1 mx memories update --name \"${NAME}\" --content ..."
+  echo ""
+  echo "Otherwise fetch the head first and edit it, preserving existing content:"
+  echo "    mx memories get --name \"${NAME}\"   # then append/edit, don't replace"
+  echo ""
+} >&2
+exit 2

package/dist/agent-config/hooks/reload-checkpoint.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# reload-checkpoint.sh — Claude Code SessionStart hook (matcher: compact)
+# Re-injects the auto-checkpoint memory after context compaction.
+#
+# Fires on: SessionStart with source=compact (after compaction)
+# Input: JSON on stdin with session_id, source
+# Output: stdout text is injected into Claude's context
+# Exit: always 0
+
+# Fail-open: any error → start session without checkpoint injection
+trap 'exit 0' ERR
+
+# ── 1. Determine worktree name ──────────────────────────────────────────
+
+WORKTREE_NAME="${CLAUDE_WORKTREE_NAME:-}"
+
+# If no worktree env var, try to detect from cwd
+if [[ -z "$WORKTREE_NAME" ]]; then
+  INPUT=$(cat)
+  CWD=$(echo "$INPUT" | jq -r '.cwd // ""' 2>/dev/null) || true
+  if [[ "$CWD" == */.worktrees/* ]]; then
+    WORKTREE_NAME=$(echo "$CWD" | sed 's|.*/.worktrees/||' | cut -d'/' -f1)
+  fi
+fi
+
+# Can't identify worktree → nothing to reload
+if [[ -z "$WORKTREE_NAME" ]]; then
+  exit 0
+fi
+
+command -v mx >/dev/null 2>&1 || exit 0
+
+# ── 2. Retrieve checkpoint memory ───────────────────────────────────────
+
+CHECKPOINT=$(mx memories get --name "auto-checkpoint-${WORKTREE_NAME}" --format json --detail minimal 2>/dev/null)
+
+if [[ -z "$CHECKPOINT" || "$CHECKPOINT" == *"not found"* || "$CHECKPOINT" == *"404"* ]]; then
+  exit 0
+fi
+
+# Extract just the content field from the JSON response
+CONTENT=$(echo "$CHECKPOINT" | jq -r '.content // empty' 2>/dev/null)
+
+if [[ -z "$CONTENT" ]]; then
+  exit 0
+fi
+
+# ── 3. Output checkpoint for context injection ──────────────────────────
+# Text written to stdout by SessionStart hooks is added to Claude's context.
+
+cat <<EOF
+## Auto-Checkpoint Recovery
+
+The following checkpoint was automatically saved before the last context compaction.
+Use it to resume your work. The checkpoint captures what you were working on,
+which files were involved, and the recent conversation context.
+
+---
+
+${CONTENT}
+
+---
+
+**Action:** Review this checkpoint and continue where you left off.
+If you need more context, search memories with: mx memories search --query "<topic>" --recent 24h
+EOF
+
+exit 0

package/dist/agent-config/hooks/set-terminal-appearance.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# set-terminal-appearance.sh — Claude Code SessionStart hook
+# Sets the VS Code terminal tab title and color for the agent team.
+#
+# Fires on: SessionStart (all — no matcher filter)
+# Input: JSON on stdin (ignored)
+# Output: none (side-effect: writes OSC sequences to /dev/tty)
+# Exit: always 0
+#
+# Reads CLAUDE_TEAM_NAME and CLAUDE_TEAM_COLOR from environment
+# (set by mx-agent start via launchClaudeSession).
+# Writes escape sequences to /dev/tty to bypass Claude's stdin/stdout,
+# ensuring the tab title/color persist after Claude's TUI initializes.
+
+TEAM_NAME="${CLAUDE_TEAM_NAME:-}"
+TEAM_COLOR="${CLAUDE_TEAM_COLOR:-}"
+
+# Nothing to set — not launched via mx-agent
+if [[ -z "$TEAM_NAME" ]]; then
+  exit 0
+fi
+
+# Drain stdin (hook contract requires reading input)
+cat > /dev/null 2>&1 || true
+
+# OSC 0: Set terminal tab title
+printf '\033]0;%s\007' "$TEAM_NAME" > /dev/tty 2>/dev/null || true
+
+# OSC 633;P;tabColor: Set VS Code tab color (VS Code 1.94+ shell integration)
+if [[ -n "$TEAM_COLOR" ]]; then
+  printf '\033]633;P;tabColor=%s\007' "$TEAM_COLOR" > /dev/tty 2>/dev/null || true
+fi
+
+exit 0