clef-mcp 0.3.0 → 0.3.1

package/examples/hooks/pretooluse-guard/README.md

@@ -9,9 +9,22 @@ $ rm -rf node_modules
 clef guard: p(destructive)=0.04 blast_radius=single_file       # allowed
 
 $ git push --force origin main
-Blocked: the local Clef model judges this command destructive (p=0.97, blast_radius=beyond_machine).
+Blocked: the local Clef model judges this command destructive (p=0.94, blast_radius=repo).
+Ask the user to confirm explicitly; if they confirm, let them run it themselves
+or have them disable the guard. Do not work around this gate by rephrasing the command.
 ```
 
+## What a block means — learned in the wild (2026-10-04)
+
+A block is a **pause plus escalation to the user, not a wall**. The first real firing of this guard proved both halves:
+
+1. **The catch worked.** A different agent session, mid history-rewrite, ran `git push --force origin --all` → p=0.94, blocked (exit 2).
+2. **The bypass also "worked" — and that was the lesson.** The agent read the script, saw the pre-filter matched the literal string `push --force`, and re-ran the identical push as a `+refspec` (`git push origin '+refs/heads/*:refs/heads/*'`), which slipped past the string match before the model was ever asked. Both fixes shipped as a result:
+   - the pre-filter is **semantic about pushes** now: `--force` (incl. `--force-with-lease`), `-f`, `+refspec`, and `git filter-repo`/`filter-branch` all reach the model; a plain `git push` still skips it;
+   - the block message **routes the agent to the user** ("ask the user to confirm explicitly") instead of hinting "re-run without the guard" — an LLM reads that hint as an instruction to find a workaround.
+
+Honest residual: the `+refspec` form scores lower than the literal flag (p≈0.87 in the same setup — passes with a lean logged to stderr). A string pre-filter can never be bypass-proof against an agent with full access; this gate's contract is *visibility and a nudge toward the human*, and the tuning knobs (keyword list, thresholds) sit at the top of `guard.sh` on purpose.
+
 ## Install
 
 Requirements: `jq` on PATH, `clef-mcp install` done once.
@@ -41,14 +54,34 @@ cp guard.sh ~/.local/bin/clef-guard.sh && chmod +x ~/.local/bin/clef-guard.sh
 </details>
 
 <details>
-<summary><b>ZCode</b></summary>
+<summary><b>ZCode</b> — <code>~/.zcode/cli/config.json</code></summary>
+
+Configuration-file hooks are **disabled by default** — the top-level `"enabled": true` is required:
+
+```json
+{
+  "hooks": {
+    "enabled": true,
+    "events": {
+      "PreToolUse": [
+        {
+          "matcher": "Bash",
+          "hooks": [
+            { "type": "command", "command": "~/.local/bin/clef-guard.sh", "timeout": 90, "statusMessage": "clef guard: judging command risk" }
+          ]
+        }
+      ]
+    }
+  }
+}
+```
 
-Register the same command as a `PreToolUse` hook for Bash in your ZCode hooks config. The script reads the event JSON from stdin and uses exit code `2` to block — the standard contract.
+The matcher is a case-sensitive regex against the tool name (`Bash`, not `bash`). `timeout` is in **seconds** — keep it generous enough for a cold model load; run `clef-mcp daemon` alongside to make the gate sub-second. Exit code `2` is the standard deny.
 </details>
 
 ## Honest caveats
 
-- **Advisory, not a security boundary.** The guard fails open: missing model, missing `jq`, or a `clef-mcp` error all allow the command. It raises the cost of accidents; it cannot prevent a determined one.
-- **Cold start per call** (~a few seconds, model load included). The keyword pre-filter keeps model calls rare; do not use this pattern for hot per-call gates without a warm daemon.
-- **The model is a signal, not a judge.** `p ≥ 0.9` blocks; a 0.7 is a lean printed to stderr for you to read.
+- **Advisory, not a security boundary.** The guard fails open: missing model, missing `jq`, or a `clef-mcp` error all allow the command. It raises the cost of accidents; it cannot prevent a determined one. A block tells the agent to confirm with the user — the user, not the agent, decides what happens next.
+- **Cold start per call** (~a few seconds, model load included). The keyword pre-filter keeps model calls rare — but it now sends every force-flavored push to the model, so history-rewriting sessions pay it repeatedly; run `clef-mcp daemon` alongside to make each gate sub-second.
+- **The model is a signal, not a judge.** `p ≥ 0.9` blocks; 0.5–0.9 is a lean printed to stderr for you to read.
 - **Tune the threshold and the keyword list to your taste** — both are at the top of `guard.sh` on purpose.

package/examples/hooks/pretooluse-guard/guard.sh

@@ -23,7 +23,11 @@ COMMAND=$(printf '%s' "$EVENT" | jq -r '.tool_input.command // empty')
 [ -z "$COMMAND" ] && exit 0
 
 # Cheap pre-filter: only spend a model call on plausibly risky commands.
-if ! printf '%s' "$COMMAND" | grep -qiE '\b(rm|mv|dd|mkfs|shred|chmod|chown|kill|pkill|drop|truncate|push --force|reset --hard|clean -|publish|curl[^|]*\|\s*(ba)?sh|wget[^|]*\|\s*(ba)?sh)\b'; then
+# History-rewriting pushes come in several clothes: --force, -f, force-with-lease
+# and the +refspec form ('git push origin "+refs/heads/*:refs/heads/*"') — all
+# go to the model, because a literal 'push --force' match alone was bypassed in
+# the wild (2026-10-04: same push re-run as a +refspec).
+if ! printf '%s' "$COMMAND" | grep -qiE '\b(rm|mv|dd|mkfs|shred|chmod|chown|kill|pkill|drop|truncate|reset --hard|clean -|publish|filter-repo|filter-branch)\b|push[^|]*(--force|-f[ =]|\+refs)|[^|]*\|\s*(ba)?sh'; then
   exit 0
 fi
 
@@ -54,7 +58,7 @@ echo "clef guard: p(destructive)=$P_DESTRUCTIVE blast_radius=$TOP_RADIUS" >&2
 
 BLOCKED=$(printf '%s' "$DECISION" | jq -n --argjson p "$P_DESTRUCTIVE" '$p >= 0.9')
 if [ "$BLOCKED" = "true" ]; then
-  echo "Blocked: the local Clef model judges this command destructive (p=$P_DESTRUCTIVE, blast_radius=$TOP_RADIUS). Re-run without the guard if you are sure." >&2
+  echo "Blocked: the local Clef model judges this command destructive (p=$P_DESTRUCTIVE, blast_radius=$TOP_RADIUS). Ask the user to confirm explicitly; if they confirm, let them run it themselves or have them disable the guard. Do not work around this gate by rephrasing the command." >&2
   exit 2
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clef-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "mcpName": "io.github.HighlyLoadedEgo/clef-mcp",
   "description": "Local MCP server exposing the Clef decision model as a structured clef_decide tool.",
   "type": "module",