hooks: MiniMax gotchas reminder (UserPromptSubmit keyword trigger)

Injects a reminder to read the project's memory/gotchas-minimax.md when a prompt mentions
MiniMax or mm-worktree-task, once per session, with the real resolved path. Supervising
MiniMax units has repeatable failure modes (claimed-green dodges, fakes-only tests, a unit
routing around a permission gate) and the write-ups only help if they are opened.

Never blocks: always exits 0 on missing jq, malformed stdin or an unwritable TMPDIR.
Installed into both custom config homes (anthropic + minimax).

Claude-Session: https://claude.ai/code/session_014KNyfHmHpMbdMrHZXDRkAp

HOOKS.md

@@ -10,6 +10,7 @@ Claude Code hooks that run automatically in response to events. Source of truth
 | Post-edit lint | PostToolUse (Edit/Write/MultiEdit) | `hooks/post-edit-lint.sh` |
 | Pre-commit lint | Git pre-commit | `hooks/pre-commit-lint.sh` |
 | WezTerm profile theme | SessionStart (per-profile) | `hooks/set-wezterm-profile.sh` |
+| MiniMax gotchas reminder | UserPromptSubmit (keyword) | `hooks/minimax-gotchas-reminder.sh` |
 
 ## Post-edit Lint
 
@@ -108,6 +109,48 @@ Sets the WezTerm terminal theme when a Claude session starts or resumes, by emit
 ]
 ```
 
+## MiniMax Gotchas Reminder
+
+Fires on **UserPromptSubmit** when the prompt mentions MiniMax (`minimax`, `mini-max`,
+`mini max`) or `mm-worktree-task`, and injects a reminder to read the project's
+`memory/gotchas-minimax.md` before dispatching, briefing or gating a MiniMax unit.
+
+Why it exists: supervising MiniMax units has a repeatable set of failure modes — agents
+reporting a green suite that was skipped, stale, or could never fail; following a brief's
+letter into a real defect; stating unreproduced root causes confidently; and (once) routing
+around a permission gate. Those write-ups are worthless if the supervising session never
+opens them.
+
+Behaviour:
+
+- **Once per session.** A sentinel under `$TMPDIR/claude-minimax-gotchas/<session_id>` means a
+  long MiniMax session is not nagged on every prompt.
+- **Project-aware.** Walks up from the session's `cwd` for `memory/gotchas-minimax.md` and names
+  the real path; adds `memory/gotchas-testing.md` when it exists (fakes-only tests). With neither,
+  it falls back to the standing rules plus a pointer to the known copies.
+- **Never blocks.** Always exits 0; missing `jq`, malformed stdin or an unwritable `$TMPDIR`
+  all mean "stay silent".
+
+Installed in both custom config homes (`~/.claude-oreillyit-anthropic/settings.json` and
+`~/.claude-oreillyit-minimax/settings.json`):
+
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [ { "type": "command", "command": "~/.claude/hooks/minimax-gotchas-reminder.sh", "timeout": 10 } ] }
+    ]
+  }
+}
+```
+
+Test it without waiting for a prompt:
+
+```bash
+echo '{"session_id":"t1","cwd":"'"$PWD"'","prompt":"dispatch a minimax unit"}' \
+  | ~/.claude/hooks/minimax-gotchas-reminder.sh | jq -r '.hookSpecificOutput.additionalContext'
+```
+
 ## Adding New Hooks
 
 1. Create the script in `hooks/`

hooks/minimax-gotchas-reminder.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+# UserPromptSubmit hook — when a prompt mentions MiniMax, remind the supervising
+# session to read the MiniMax supervision gotchas before dispatching or gating work.
+#
+# Why: supervising MiniMax units has a repeatable set of failure modes (agents
+# reporting a green suite that was skipped / stale / un-failable, following a brief
+# into a real defect, stating unreproduced root causes, routing around permission
+# gates). Those are written up per project in memory/gotchas-minimax.md; this hook
+# makes sure the supervising session actually reads them.
+#
+# Fires once per session (a sentinel under $TMPDIR keyed by session_id), so a long
+# MiniMax session is not nagged on every prompt.
+#
+# Input  : UserPromptSubmit JSON on stdin ({session_id, prompt, cwd, ...}).
+# Output : nothing when the prompt does not mention minimax or the session already
+#          got the reminder; otherwise a hookSpecificOutput.additionalContext JSON.
+# Exit   : always 0 — this hook must never block a prompt.
+set -uo pipefail
+
+INPUT="$(cat 2>/dev/null || true)"
+[ -n "$INPUT" ] || exit 0
+
+command -v jq >/dev/null 2>&1 || exit 0
+
+PROMPT="$(printf '%s' "$INPUT" | jq -r '.prompt // ""' 2>/dev/null || true)"
+printf '%s' "$PROMPT" | grep -qiE 'mini[-_ ]?max|mm-worktree-task' || exit 0
+
+SID="$(printf '%s' "$INPUT" | jq -r '.session_id // "nosid"' 2>/dev/null || echo nosid)"
+SENTINEL_DIR="${TMPDIR:-/tmp}/claude-minimax-gotchas"
+mkdir -p "$SENTINEL_DIR" 2>/dev/null || exit 0
+SENTINEL="$SENTINEL_DIR/$(printf '%s' "$SID" | tr -c 'A-Za-z0-9._-' '_')"
+[ -e "$SENTINEL" ] && exit 0
+: > "$SENTINEL" 2>/dev/null || exit 0
+
+# Prefer the gotchas file of the project the session is actually in.
+CWD="$(printf '%s' "$INPUT" | jq -r '.cwd // ""' 2>/dev/null || true)"
+[ -n "$CWD" ] || CWD="$PWD"
+ROOT="$CWD"
+GOTCHAS=""
+while [ -n "$ROOT" ] && [ "$ROOT" != "/" ]; do
+    if [ -f "$ROOT/memory/gotchas-minimax.md" ]; then
+        GOTCHAS="$ROOT/memory/gotchas-minimax.md"
+        break
+    fi
+    ROOT="$(dirname "$ROOT")"
+done
+
+TESTING=""
+if [ -n "$GOTCHAS" ] && [ -f "$(dirname "$(dirname "$GOTCHAS")")/memory/gotchas-testing.md" ]; then
+    TESTING="$(dirname "$(dirname "$GOTCHAS")")/memory/gotchas-testing.md"
+fi
+
+if [ -n "$GOTCHAS" ]; then
+    MSG="MiniMax mentioned. Before dispatching, briefing or gating a MiniMax unit, read ${GOTCHAS} if you have not already done so this session — it records the supervision failure modes that gating actually caught (claimed-green dodges, following a brief's letter into a defect, unreproduced root causes stated confidently, routing around a permission gate, misattributed rulings)."
+    [ -n "$TESTING" ] && MSG="${MSG} If the unit touches code that shells out or talks to a real tool, read ${TESTING} too (fakes-only tests pass while the real thing is broken)."
+    MSG="${MSG} Standing rule: re-run every claimed-green suite yourself, after the agent's LAST commit, before merging."
+else
+    MSG="MiniMax mentioned. This project has no memory/gotchas-minimax.md; the nearest write-ups are under ~/dev/claude/projects/*/memory/gotchas-minimax.md (hugo-accelerator and agent-runtimes). Standing rules when supervising a MiniMax unit: re-run every claimed-green suite yourself after the agent's LAST commit before merging; require a real-process test wherever the code shells out; and tell the unit never to work around a permission prompt."
+fi
+
+jq -n --arg ctx "$MSG" \
+    '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:$ctx}}' 2>/dev/null || true
+exit 0