stack/tools/unslop-hook

unslop-hook

Mechanical AI-tell enforcement for pi seats and for managed sessions on both harnesses (row 66, #1559). Anti-drift gate for the writing standard in SYSTEM.md / ms-unslop: prose distribution alone decays over long sessions; this check cannot forget.

• lists.json: committed machine source for every list the checker enforces: words, phrases, punct rules, regex patterns, density thresholds. Each entry carries provenance (ms-unslop:<pattern id> or system-md), the mention convention, and the documented divergence of the density gate from SYSTEM.md's outright em-dash ban. Edit lists here, not in code.
• unslop-check.js: dependency-free checker (node CLI + module) driven by lists.json. Loads and schema-validates the lists on first use and hard-fails closed: empty, unparseable, or invalid lists throw. Detects banned vocabulary, chatbot/sycophancy phrases, filler phrases, em/en dashes, curly quotes, not just X but Y. Strips fenced and inline code first, so quoted code is never flagged. Exit 0 clean, 1 violations, 2 gate broken (lists unreadable, never a clean verdict).
• extension.ts: pi extension. message_end checks finalized assistant text and notifies the operator (TUI/RPC). before_agent_start reads the most recent assistant reply from the session file (walking getBranch() from its end: pi returns the branch root first, and before row 66 the walk read the session's first reply every turn) and, if it carries tells, injects a correction notice the model sees on its next turn. /unslop reports session stats. Violation state lives in the session file, so the injection path survives restart, resume, fork, and reload (an in-memory pending flag was measured dead across print-mode turns, 2026-08-19). A broken lists.json fails closed: checks stop, broken_lists / skipped_broken events log the reason, operator notified once, seat keeps running.
• claude-hook.js: the same check for Claude Code (row 66). A managed session's settings.json runs it twice: stop checks each assistant message of the turn from the transcript and logs checked or flagged, and prompt (UserPromptSubmit) prints the extension's correction notice as additionalContext when the last reply had tells, once per reply. Claude Code writes one transcript line per content block, so adjacent lines with one message id are one reply, keyed by the first line's uuid. A broken lists.json logs broken_lists and checks nothing; any other fault logs hook_failed. It always exits 0 and never blocks.
• Each finding carries source, its entry's pattern id in lists.json (ms-unslop:7), so the counts can be read per pattern.
• test-unslop-check.js: unit tests with red and green controls.

Use

node test-unslop-check.js                                   # suite
node unslop-check.js <file>                                 # CLI check
UNSLOP_LISTS=<path> node unslop-check.js <file>             # alt lists location
pi -e ~/.mosaic/tools/unslop-hook/extension.ts              # ad-hoc load
# deploy: copy dir to ~/.pi/agent/extensions/unslop-hook/ or seat .pi
#         equivalent, or list it in settings.json "extensions"

Env: MOSAIC_UNSLOP_HOOK=0 disables. MOSAIC_UNSLOP_LOG=<path> appends JSONL events (loaded / flagged / notice_injected / checked / broken_lists / skipped_broken) for headless evidence. UNSLOP_LISTS=<path> overrides the lists.json location for both CLI and extension.

In a managed session the runner sets MOSAIC_UNSLOP_LOG to <run>/unslop.jsonl, reads it after each turn and adds a short note to the next reply the session sends, which mosaic talk and mosaic follow print. A broken check is told there once a run. unslopCounts() in packages/harness/src/runner.mjs reads the counts after the session ends. The session environment's allowlist doesn't pass MOSAIC_UNSLOP_HOOK or UNSLOP_LISTS, so a managed session can't turn the check off or swap its lists.

Verified here (2026-08-19)

• Unit suite 24/24 (8 behavioral, 11 loader/CLI, 5 review follow-up), red and green controls both exercised, including exit-2 on broken lists and on an unreadable input file (S3).
• CLI: slop file exit 1, clean file exit 0, broken lists exit 2 with the fault named on stderr.
• Extension, healthy path (print mode, zai/glm-5.3:low): startup probe loads lists.json, reply checked clean.
• Extension, broken-lists path (print mode): broken_lists at startup, skipped_broken per turn, seat survives, reply still delivered.
• Earlier live evidence (pre-C1, inline lists): forced-slop turn flagged; fresh-process follow-up injected the notice and the reply came back clean; full TUI trial (notify line, injection, /unslop stats) on session vision-unslop.
• Log evidence in session scratchpad.

Verified here (2026-10-20, row 66)

• Unit suite 28/28: the source field, replies() grouping, the Claude Code hook's stop and prompt paths, its off switch, a broken lists.json at stop and at prompt, and bad hook input (hook_failed, exit 0).
• Managed sessions on both harnesses against the test API (packages/harness/tests/pi-session.test.mjs, claude-session.test.mjs): a reply with a tell gets the notice on the next turn, a clean reply gets none, the operator note rides the next reply, a broken lists.json fails closed with the session still answering, and the counts read back after the session ends.

Limits

• /unslop command not tested headless (print mode has no command surface); it is a thin stats wrapper.
• En dash flag fires on typographic ranges too (2–3); acceptable for fleet prose, revisit if it noisifies technical writing.
• Notice injection is a nudger, not a blocker. Output already streamed to the user stays as-is; correction lands on the next turn.
• A broken lists.json latches for the session: repairing the file mid-session does not revive checks until the seat restarts. Acceptable for an advisory gate (review S1).
• The fail-closed operator notification requires a UI. Print-mode sessions log skipped_broken but notify nobody (review S2). Managed sessions are the exception: the runner tells the operator in the next reply (row 66).
• In a managed session the log sits in the run directory, which the session can write. The counts are the session's own report, not host evidence.
• The extension's per-reply dedupe is in memory. After a restart the same reply can get a second notice.
• On the first turn of a new Claude Code session the transcript may not hold the reply when Stop runs; the hook then checks last_assistant_message and logs an empty entryId.
• The word/phrase lists are the mechanical subset of ms-unslop only, keyed to pattern ids in lists.json. Style judgments (voice, rhythm, structure) stay in the skill, not the gate.

Promotion path

Stack issue (A4): checker shared as the single source for a matching Claude Code Stop-hook script; lists versioned beside SYSTEM.md contract text. Row 66 did the first part: claude-hook.js runs the same checker and lists. Blocking a reply (Q84 option B) is a later decision.