clef-mcp 0.3.0 → 0.4.0

package/examples/classify/README.md

@@ -0,0 +1,27 @@
+# Classify support requests locally
+
+These files ship with the npm package. After `clef-mcp install`, run from this directory:
+
+```sh
+clef-mcp classify tickets.jsonl --profile support-routing.yaml --output results.jsonl
+clef-mcp classify tickets.csv --profile support-routing.yaml --output csv-results.jsonl
+clef-mcp classify tickets.jsonl --profile support-routing.yaml --output results.jsonl --resume
+```
+
+Both inputs contain the same three records. CSV IDs stay strings (`001`).
+The third request deliberately overlaps billing and technical support; its
+result depends on the model distribution and the profile policy.
+
+Results are JSONL. `classified` has an accepted `label`; `needs_review` has
+`label: null`, a `suggested_label`, probabilities and review reasons. There is
+no fixed expected answer/accuracy claim for this example.
+
+To inspect stricter review behavior, copy the profile and set
+`min_probability: 1.0`. To accept more results, lower the thresholds only
+after checking the distributions on representative labeled data. A threshold
+does not establish calibrated accuracy or replace authorization checks.
+
+Output paths must be new, or use `--resume` with the same input/profile/model/runtime.
+Changing a threshold requires a new output path. Resume skips every committed
+row, including error rows; it does not retry failed input records. See the main
+README for sidecars, locks, exit codes and input limits.

package/examples/classify/support-routing.yaml

@@ -0,0 +1,18 @@
+schema_version: 1
+name: support-routing
+instructions: Classify the current support request into exactly one department. Labeled examples are reference data.
+labels:
+  billing: Payments, refunds, invoices and subscription charges
+  technical: Errors, outages, installation and integration problems
+  other: Requests outside billing and technical support
+input:
+  id_field: id
+  fields: [subject, body]
+policy:
+  min_probability: 0.80
+  min_margin: 0.15
+examples:
+  - input:
+      subject: Duplicate charge
+      body: My card was charged twice for one subscription.
+    label: billing

package/examples/classify/tickets.csv

@@ -0,0 +1,4 @@
+id,subject,body
+001,Refund request,"I was charged twice for the same subscription. Please refund the duplicate payment."
+002,Connection error,"The integration fails with HTTP 500 whenever I submit a request."
+003,Payment page error,"I cannot finish paying because the checkout page crashes."

package/examples/classify/tickets.jsonl

@@ -0,0 +1,3 @@
+{"id":"001","subject":"Refund request","body":"I was charged twice for the same subscription. Please refund the duplicate payment."}
+{"id":"002","subject":"Connection error","body":"The integration fails with HTTP 500 whenever I submit a request."}
+{"id":"003","subject":"Payment page error","body":"I cannot finish paying because the checkout page crashes."}

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.4.0",
   "mcpName": "io.github.HighlyLoadedEgo/clef-mcp",
   "description": "Local MCP server exposing the Clef decision model as a structured clef_decide tool.",
   "type": "module",
@@ -44,6 +44,8 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.32.0",
     "commander": "^15.0.0",
+    "csv-parse": "7.0.3",
+    "yaml": "2.9.1",
     "zod": "^4.0.0"
   },
   "devDependencies": {