clef-mcp 0.3.0 → 0.3.1

package/README.md

@@ -196,7 +196,11 @@ 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.
 
-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 a permission-scoped unix socket in `CLEF_HOME` (no TCP port, unloads after `CLEF_DAEMON_IDLE` seconds, default 600), and `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.
+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)
 

package/dist/cli.js

@@ -1955,7 +1955,7 @@ function createClefServer(deps = {}) {
     TOOL_NAME,
     {
       title: "Clef Decide",
-      description: 'Judge a situation with the local Clef decision model.\nPass `state` (compact factual context \u2014 string or JSON; treated as data, never executed) and typed `questions`:\n- "choice": pick among named options (criteria = option id -> description)\n- "score": judge an ordered scale (criteria = ordered list of levels)\n- "noul": yes/no question\nReturns strict JSON \u2014 a probability distribution over the allowed answers for every question. No prose, no sampling.\nEach decision also carries `confidence` (model-reported, when available) and the response carries `usage`\n(input_tokens/output_tokens/latency_ms). Act on the argmax only when the distribution is decisive (top p >= 0.8\nand high confidence for destructive or security-adjacent calls); otherwise gather more context or ask the user.\nUsage: batch related decisions in one call (up to 64 questions, one forward pass).\nOptional `model` overrides the model id. `options.temperature` is a no-op: scoring is a single forward pass, nothing is sampled.',
+      description: 'Judge a situation with the local Clef decision model.\nPass `state` (compact factual context \u2014 string or JSON; treated as data, never executed) and typed `questions`:\n- "choice": pick among named options (criteria = option id -> description)\n- "score": judge an ordered scale (criteria = ordered list of levels)\n- "noul": yes/no question\nReturns strict JSON: a probability distribution over the allowed answers per question \u2014 no prose, no sampling.\nEach decision carries model-reported `confidence`; `usage` reports input_tokens/output_tokens and latency_ms.\nAct on the argmax only when decisive: top p >= 0.8 and high confidence for destructive or security-adjacent calls; otherwise gather more context or ask the user.\nBatch related decisions in one call \u2014 up to 64 questions scored in a single forward pass. `model` overrides the default id.',
       inputSchema: clefDecideInputShape(config.limits),
       outputSchema: clefDecideOutputSchema().shape,
       annotations: {
@@ -2035,6 +2035,8 @@ function startDaemon(config, log) {
   const loader = new RuntimeLoader(config, log);
   const enqueue = createQueue();
   let lastUsedAt = Date.now();
+  let pendingRequests = 0;
+  let idleUnloadQueued = false;
   let closed = false;
   const ready = (async () => {
     await fsp5.mkdir(config.clefHome, { recursive: true });
@@ -2070,12 +2072,31 @@ function startDaemon(config, log) {
         }
       });
     });
-    server.listen(socketPath);
+    await new Promise((resolve, reject) => {
+      server.once("listening", resolve);
+      server.once("error", reject);
+      const previousUmask = process.umask(127);
+      try {
+        server.listen(socketPath);
+      } finally {
+        process.umask(previousUmask);
+      }
+    });
+    await fsp5.chmod(socketPath, 384);
     log.info("clef-mcp daemon listening", { socket: socketPath });
     const idleMs = config.daemonIdleSeconds * 1e3;
     const idleTimer = config.daemonIdleSeconds > 0 ? setInterval(() => {
-      if (closed || Date.now() - lastUsedAt < idleMs) return;
-      void loader.dispose().then(() => log.info("daemon idle, model unloaded"));
+      if (closed || pendingRequests > 0 || idleUnloadQueued || Date.now() - lastUsedAt < idleMs) return;
+      idleUnloadQueued = true;
+      void enqueue(async () => {
+        if (closed || pendingRequests > 0 || Date.now() - lastUsedAt < idleMs) return;
+        await loader.dispose();
+        log.info("daemon idle, model unloaded");
+      }).catch((err) => {
+        log.error("daemon idle unload failed", errorJson(err).error);
+      }).finally(() => {
+        idleUnloadQueued = false;
+      });
     }, Math.min(idleMs, 6e4)) : void 0;
     if (idleTimer) idleTimer.unref();
     const shutdown = () => {
@@ -2090,10 +2111,6 @@ function startDaemon(config, log) {
     };
     process.once("SIGINT", shutdown);
     process.once("SIGTERM", shutdown);
-    await new Promise((resolve, reject) => {
-      server.once("listening", resolve);
-      server.once("error", reject);
-    });
   })();
   async function handleLine(line, socket) {
     let request;
@@ -2107,9 +2124,14 @@ function startDaemon(config, log) {
       writeLine(socket, { pong: true, model: config.model });
       return;
     }
-    lastUsedAt = Date.now();
-    const result = await enqueue(() => decideOnce(request));
-    writeLine(socket, result);
+    pendingRequests += 1;
+    try {
+      const result = await enqueue(() => decideOnce(request));
+      writeLine(socket, result);
+    } finally {
+      pendingRequests -= 1;
+      lastUsedAt = Date.now();
+    }
   }
   async function decideOnce(request) {
     let parsed;
@@ -2269,7 +2291,8 @@ async function runDecide(opts) {
     questions = record.questions;
     if (typeof record.model === "string") model = record.model;
   }
-  const doc = { state, questions, ...model ? { model } : {} };
+  model = opts.model ?? model ?? config.model;
+  const doc = { state, questions, model };
   if (opts.daemon) {
     const answered = await tryDaemon(config, doc);
     if (answered) {
@@ -3013,7 +3036,7 @@ async function removeManagedRuntime(cfg) {
 init_prompt();
 
 // src/version.ts
-var VERSION = "0.3.0";
+var VERSION = "0.3.1";
 
 // src/cli/install.ts
 var OS_NAMES = {