From 729b065f448bee7df66743c7b085c2c718c5b62e Mon Sep 17 00:00:00 2001 From: Paul O'Reilly Date: Wed, 23 Sep 2026 13:51:54 +1200 Subject: [PATCH] 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 | 43 +++++++++++++++++++++ hooks/minimax-gotchas-reminder.sh | 63 +++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+) create mode 100755 hooks/minimax-gotchas-reminder.sh diff --git a/HOOKS.md b/HOOKS.md index c87bb4c..248624d 100644 --- a/HOOKS.md +++ b/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/` 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/` diff --git a/hooks/minimax-gotchas-reminder.sh b/hooks/minimax-gotchas-reminder.sh new file mode 100755 index 0000000..45eb658 --- /dev/null +++ b/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