clef-mcp 0.2.1 → 0.3.1

package/README.md

@@ -81,19 +81,22 @@ Sweet spot: **decision points inside agent loops** — next action, routing, cla
 | `score` | ordered list (index = score) | probability per level |
 | `noul` | optional `{"true": "...", "false": "..."}` | `{"true": p, "false": 1-p}` |
 
-Response — strictly structured, never prose:
+Response — strictly structured, never prose. Each decision carries the model-reported `confidence` (when the runtime sends it), plus token `usage` for the call:
 
 ```json
 {
   "model": "clef-flash",
   "decisions": {
-    "next_action": { "answer": { "inspect": 0.72, "modify": 0.12, "test": 0.14, "ask_user": 0.02 } },
-    "confidence":  { "answer": { "very_low": 0.01, "low": 0.04, "medium": 0.18, "high": 0.61, "very_high": 0.16 } },
+    "next_action": { "answer": { "inspect": 0.72, "modify": 0.12, "test": 0.14, "ask_user": 0.02 }, "confidence": 0.83 },
+    "confidence":  { "answer": { "very_low": 0.01, "low": 0.04, "medium": 0.18, "high": 0.61, "very_high": 0.16 }, "confidence": 0.61 },
     "is_outage":   { "answer": { "true": 0.9, "false": 0.1 } }
-  }
+  },
+  "usage": { "input_tokens": 228, "output_tokens": 0, "latency_ms": 512 }
 }
 ```
 
+Act on the argmax only when the distribution is decisive — top p ≥ 0.8 and high `confidence` for destructive or security-adjacent calls.
+
 Batch up to **64 questions per call** — they are scored in one forward pass. `state` is treated strictly as **data**: never executed, never interpreted as instructions for the server.
 
 ## Prompts & resources
@@ -178,6 +181,27 @@ args = []
 
 Ready-made snippets: [`examples/`](examples/).
 
+## Scripting & hooks
+
+No MCP client required — hooks, CI jobs and shell scripts call the same model one-shot:
+
+```bash
+# Full document on stdin
+echo '{"state": "checkout 500s after deploy", "questions": {"is_outage": {"type": "noul", "instructions": "Is a service down?"}}}' \
+  | clef-mcp decide
+
+# Or split across files
+clef-mcp decide --questions questions.json --state state.json
+```
+
+stdout carries the strict JSON result (same shape as the MCP tool, including `confidence` and `usage`); errors go to stderr as structured JSON with exit codes: `2` invalid input, `3` model not installed, `4` runtime missing. `decide` never downloads anything.
+
+Model selection: `--model <id>` overrides the input document's `model`, which overrides `CLEF_MODEL` (default: `clef-flash`). The same precedence applies with `--daemon`.
+
+Each plain `decide` invocation is a cold start (model load included, a few seconds) — fine for gates and triage. For repeated calls, start `clef-mcp daemon` once: it keeps the model warm on an owner-only (`0600`) unix socket in `CLEF_HOME` (no TCP port, unloads after `CLEF_DAEMON_IDLE` seconds of inactivity following the last completed decision, default 600). Active and queued requests prevent idle unloading. `clef-mcp decide --daemon` answers in well under a second, falling back to a cold run when no daemon is running. See [`examples/hooks/`](examples/hooks/) for a PreToolUse guard and a GitHub Action recipe.
+
+The PreToolUse guard blocks a command when the model judges it destructive (p ≥ 0.9) and tells the agent to **ask the user** — a block is a pause plus escalation, not a wall; the gate is advisory by design and says so. First real firing on day one: caught a history-rewrite force push (p=0.94) and surfaced its own bypass vector, which is now fixed and documented in the recipe.
+
 ## Teach your agent (skill)
 
 The schema tells the client *what* `clef_decide` accepts; agents also need to know *when* to reach for it and *how* to frame decisions. The bundled [`clef-decisions`](skills/clef-decisions/SKILL.md) skill covers decision patterns, batching, criteria writing, distribution interpretation and error recovery:
@@ -210,6 +234,8 @@ The `ClefRuntime` interface (`load / decide / unload / health`) isolates the eng
 
 ```bash
 clef-mcp              # run the MCP server on stdio (default command)
+clef-mcp decide       # one-shot decision (no MCP session): JSON in, JSON out — for hooks, CI, scripts
+clef-mcp daemon       # keep the model warm on a local unix socket; `decide --daemon` uses it
 clef-mcp install      # detect hardware → download model + runtime → verify checksum → verify inference
 clef-mcp setup        # register the MCP server + agent skill in zcode / claude-code / codex / cursor
 clef-mcp models       # list models/quantizations and install status
@@ -246,6 +272,7 @@ Switch at runtime with `CLEF_RUNTIME=mlx` (must be set for the MCP server proces
 | `CLEF_LLAMA_RELEASE_TAG` | latest nightly | Pin the managed llama.cpp build |
 | `CLEF_LLAMA_BATCH` | `8192` | llama.cpp physical batch (multi-question requests) |
 | `CLEF_MLX_UV` | `uv` on PATH | Explicit uv binary (MLX runtime) |
+| `CLEF_DAEMON_IDLE` | `600` | Seconds of idle before the daemon unloads the model (0 = never) |
 | `CLEF_MAX_QUESTIONS` | `64` | Max questions per call |
 | `CLEF_MAX_STATE_BYTES` | `1048576` | Max serialized `state` size |
 | `CLEF_MAX_INSTRUCTION_CHARS` | `10000` | Max chars per question instructions |