@ratifia/mcp 0.4.1 → 0.5.0

package/dist/index.js

@@ -97,7 +97,117 @@ function buildResponseSpec(responseType, options, allowMultiple) {
         max: allowMultiple ? specOptions.length : 1,
     };
 }
-const server = new McpServer({ name: 'ratifia', version: '0.4.1' }, {
+// ─── Gate mode (Claude Code PreToolUse hook) ─────────────────────────────────
+/** Read the hook payload from stdin (Claude Code pipes the PreToolUse JSON). */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY)
+            return resolve('');
+        let data = '';
+        process.stdin.setEncoding('utf8');
+        process.stdin.on('data', (c) => (data += c));
+        process.stdin.on('end', () => resolve(data));
+        setTimeout(() => resolve(data), 3000); // don't hang if the stream never ends
+    });
+}
+/** Emit Claude Code's PreToolUse permission decision (allow | deny) as JSON. */
+function gateDecision(decision, reason) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: decision,
+            permissionDecisionReason: reason,
+        },
+    }));
+}
+/**
+ * `ratifia-mcp gate` — a Claude Code **PreToolUse hook**. Opens a Ratifia
+ * decision for the tool call (rendered as a `tool_call` context panel), blocks
+ * until a human answers, and returns allow/deny to the harness. The "list of
+ * tools" that trigger this is the hook's matcher in settings.json; narrow it
+ * further with RATIFIA_GATED_TOOLS. Fail-CLOSED (deny) on error/timeout unless
+ * RATIFIA_GATE_FAIL_OPEN=1 — a gate that fails open is no gate.
+ */
+async function runGate() {
+    const failOpen = process.env.RATIFIA_GATE_FAIL_OPEN === '1';
+    let payload = {};
+    try {
+        payload = JSON.parse((await readStdin()) || '{}');
+    }
+    catch {
+        /* proceed with an empty payload */
+    }
+    const toolName = String(payload.tool_name ?? 'unknown_tool');
+    const toolInput = payload.tool_input ?? {};
+    // Optional allow-list: if set, only gate these tools; pass the rest through.
+    const gated = (process.env.RATIFIA_GATED_TOOLS ?? '')
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean);
+    if (gated.length > 0 && !gated.includes(toolName)) {
+        return gateDecision('allow', `not a gated tool: ${toolName}`);
+    }
+    // How long to block waiting for a human. Keep the settings.json hook `timeout`
+    // a little higher than this; on timeout we fail-closed (deny) by default.
+    const budgetMs = Math.max(10, Number(process.env.RATIFIA_GATE_TIMEOUT_SEC ?? 240)) * 1000;
+    let decisionId;
+    try {
+        const externalRunId = `gate-${Date.now()}-${Math.round(Math.random() * 1e6)}`;
+        const res = await api('/v1/worker/decisions', {
+            method: 'POST',
+            body: JSON.stringify({
+                engine: 'mcp',
+                externalRunId,
+                stepRef: `tool:${toolName}`.slice(0, 80),
+                workflowRef: 'ratifia-gate',
+                ...(APPROVER_EMAIL ? { assigneeEmail: APPROVER_EMAIL } : {}),
+                ...(POLICY ? { policy: POLICY } : {}),
+                required: true,
+                context: {
+                    prompt: `An agent wants to run the tool "${toolName}". Approve?`,
+                    blocks: [{ kind: 'tool_call', title: 'Tool call', tool: toolName, args: toolInput }],
+                },
+            }),
+        });
+        // Policy gate resolved "no approval needed" → let it run.
+        if (res.approvalNeeded === false || !res.decisionId) {
+            return gateDecision('allow', 'no approval required by policy');
+        }
+        decisionId = res.decisionId;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return gateDecision(failOpen ? 'allow' : 'deny', `ratifia gate unreachable: ${msg}`);
+    }
+    // Block until the human answers (or the budget elapses → fail-closed).
+    const start = Date.now();
+    const pollMs = 4000;
+    try {
+        for (;;) {
+            const d = await getDecision(decisionId);
+            if (d.status === 'APPROVED')
+                return gateDecision('allow', d.note ?? 'approved by reviewer');
+            if (d.status === 'REJECTED')
+                return gateDecision('deny', d.note ?? 'rejected by reviewer');
+            if (d.status !== 'PENDING')
+                return gateDecision('deny', `decision ${d.status.toLowerCase()}`);
+            if (Date.now() - start + pollMs > budgetMs) {
+                return gateDecision(failOpen ? 'allow' : 'deny', 'timed out waiting for approval');
+            }
+            await new Promise((r) => setTimeout(r, pollMs));
+        }
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return gateDecision(failOpen ? 'allow' : 'deny', `ratifia gate error: ${msg}`);
+    }
+}
+// Dispatch: `ratifia-mcp gate` runs the hook; otherwise start the MCP server.
+if (process.argv[2] === 'gate') {
+    await runGate();
+    process.exit(0);
+}
+const server = new McpServer({ name: 'ratifia', version: '0.5.0' }, {
     instructions: [
         'Ratifia lets you request a HUMAN decision or input mid-task (human-in-the-loop) and resume once it is answered.',
         '',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ratifia/mcp",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "type": "module",
   "description": "Ratifia MCP server — let an AI agent request a human decision/approval (HITL) mid-task and resume once it's answered. The agent becomes a Ratifia 'engine'.",
   "keywords": [