agent-guardrails 0.3.4 → 0.3.6

package/README.md

@@ -138,6 +138,20 @@ npx agent-guardrails setup --agent <your-agent>
 - `openhands`
 - `openclaw`
 
+### 更新 / Update
+
+如果通过 **npm 全局安装**：
+```bash
+npm update -g agent-guardrails
+```
+
+如果通过 **npx / MCP 使用**（不需要改配置文件）：
+```bash
+# 清除 npx 缓存，下次启动时自动拉取最新版
+npm cache clean --force
+# 然后重启你的 AI 工具（Claude Code / Cursor 等）即可
+```
+
 ---
 
 ## 文档 / Documentation
@@ -573,6 +587,23 @@ The daemon monitors file changes and automatically runs guardrail checks:
 | Background process | Foreground process |
 | Best for active development | Best for pre-commit/CI |
 
+### MCP Integration / MCP 集成
+
+AI agents can read daemon results via the `read_daemon_status` MCP tool — no polling needed:
+
+```json
+{
+  "mcpServers": {
+    "agent-guardrails": {
+      "command": "npx",
+      "args": ["agent-guardrails", "mcp"]
+    }
+  }
+}
+```
+
+The agent calls `read_daemon_status` after code changes to check the latest guardrail result, including findings, risks, and cost hints.
+
 ---
 
 ## CLI Fallback Quick Start

package/lib/commands/daemon.js

@@ -23,6 +23,101 @@ const DAEMON_LOG_FILE = ".agent-guardrails/daemon.log";
 const DAEMON_CONFIG_FILE = ".agent-guardrails/daemon.json";
 const DAEMON_INFO_FILE = ".agent-guardrails/daemon-info.json";
 
+/**
+ * 注入/移除 AGENTS.md 中的守护进程规则
+ */
+
+const DAEMON_AGENTS_MARKER_START = "<!-- agent-guardrails:daemon:start -->";
+const DAEMON_AGENTS_MARKER_END = "<!-- agent-guardrails:daemon:end -->";
+const DAEMON_AGENTS_BLOCK = `\n${DAEMON_AGENTS_MARKER_START}
+## Daemon Mode / 守护模式
+
+Daemon 正在运行。每次修改文件后，请调用 \`read_daemon_status\` MCP 工具检查 guardrail 结果。如果有 error 级别的 finding，在继续之前先修复。
+${DAEMON_AGENTS_MARKER_END}\n`;
+
+function injectDaemonRule(repoRoot) {
+  const agentsFile = path.join(repoRoot, "AGENTS.md");
+  if (!fs.existsSync(agentsFile)) return;
+  let content = fs.readFileSync(agentsFile, "utf8");
+  if (content.includes(DAEMON_AGENTS_MARKER_START)) return; // 已存在
+  content = content.trimEnd() + DAEMON_AGENTS_BLOCK;
+  fs.writeFileSync(agentsFile, content, "utf8");
+}
+
+function removeDaemonRule(repoRoot) {
+  const agentsFile = path.join(repoRoot, "AGENTS.md");
+  if (!fs.existsSync(agentsFile)) return;
+  let content = fs.readFileSync(agentsFile, "utf8");
+  const startIdx = content.indexOf(DAEMON_AGENTS_MARKER_START);
+  const endIdx = content.indexOf(DAEMON_AGENTS_MARKER_END);
+  if (startIdx === -1 || endIdx === -1) return;
+  content = content.slice(0, startIdx).trimEnd() + "\n" + content.slice(endIdx + DAEMON_AGENTS_MARKER_END.length).trimStart() + "\n";
+  fs.writeFileSync(agentsFile, content, "utf8");
+}
+
+/**
+ * 注入/移除 Claude Code PostToolUse hook（daemon-check）
+ */
+
+const DAEMON_HOOK_ID = "agent-guardrails:daemon-check";
+const DAEMON_HOOK_SCRIPT = ".claude/hooks/daemon-check.js";
+
+function injectClaudeHook(repoRoot) {
+  const settingsPath = path.join(repoRoot, ".claude", "settings.json");
+  const hookScriptPath = path.join(repoRoot, DAEMON_HOOK_SCRIPT);
+  const scriptSource = path.resolve(__dirname, "..", "daemon", "hooks", "daemon-check.js");
+
+  // 复制 hook 脚本到项目
+  const hookDir = path.dirname(hookScriptPath);
+  if (!fs.existsSync(hookDir)) fs.mkdirSync(hookDir, { recursive: true });
+  fs.copyFileSync(scriptSource, hookScriptPath);
+
+  // 合并到 settings.json
+  let settings = {};
+  if (fs.existsSync(settingsPath)) {
+    settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  }
+
+  if (!settings.hooks) settings.hooks = {};
+  if (!settings.hooks.PostToolUse) settings.hooks.PostToolUse = [];
+
+  // 幂等检查
+  if (settings.hooks.PostToolUse.some(h => h.id === DAEMON_HOOK_ID)) return;
+
+  settings.hooks.PostToolUse.push({
+    id: DAEMON_HOOK_ID,
+    matcher: "Edit|Write|MultiEdit",
+    hooks: [{
+      type: "command",
+      command: `node "${hookScriptPath}"`,
+      timeout: 10
+    }]
+  });
+
+  const settingsDir = path.dirname(settingsPath);
+  if (!fs.existsSync(settingsDir)) fs.mkdirSync(settingsDir, { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+}
+
+function removeClaudeHook(repoRoot) {
+  const settingsPath = path.join(repoRoot, ".claude", "settings.json");
+  const hookScriptPath = path.join(repoRoot, DAEMON_HOOK_SCRIPT);
+
+  // 删除 hook 脚本
+  if (fs.existsSync(hookScriptPath)) fs.unlinkSync(hookScriptPath);
+
+  // 从 settings.json 移除
+  if (!fs.existsSync(settingsPath)) return;
+  const settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+  if (!settings.hooks?.PostToolUse) return;
+
+  settings.hooks.PostToolUse = settings.hooks.PostToolUse.filter(h => h.id !== DAEMON_HOOK_ID);
+  if (settings.hooks.PostToolUse.length === 0) delete settings.hooks.PostToolUse;
+  if (Object.keys(settings.hooks).length === 0) delete settings.hooks;
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf8");
+}
+
 /**
  * 默认守护配置
  */
@@ -219,6 +314,8 @@ export async function startDaemon(repoRoot, options = {}) {
   const pid = await waitForPidFile(pidFile, 5000);
 
   if (pid) {
+    injectDaemonRule(repoRoot);
+    injectClaudeHook(repoRoot);
     console.log(`${t("daemon.started")}`);
     console.log(`  PID: ${pid}`);
     console.log(`\n${t("daemon.logFile")}: ${DAEMON_LOG_FILE}`);
@@ -276,6 +373,9 @@ export async function stopDaemon(repoRoot, options = {}) {
       fs.unlinkSync(pidFile);
     }
 
+    removeDaemonRule(repoRoot);
+    removeClaudeHook(repoRoot);
+
     console.log(`\n${t("daemon.stopped")}`);
     return { success: true };
   } catch (error) {

package/lib/daemon/hooks/daemon-check.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * Claude Code PostToolUse Hook — daemon-check
+ *
+ * Reads the latest daemon check result. If error-level findings exist,
+ * outputs them to stderr with exit code 2 so Claude Code sees them.
+ * Otherwise exits silently with code 0.
+ *
+ * Triggered by: Edit, Write, MultiEdit tool usage
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+const resultFile = path.join(projectDir, ".agent-guardrails", "daemon-result.json");
+
+if (!fs.existsSync(resultFile)) process.exit(0);
+
+try {
+  const data = JSON.parse(fs.readFileSync(resultFile, "utf8"));
+
+  if (!data.ok && data.result?.findings?.length > 0) {
+    const errors = data.result.findings
+      .filter(f => f.severity === "error")
+      .map(f => `[${f.code}] ${f.message}`)
+      .join("\n");
+
+    if (errors) {
+      process.stderr.write(`Guardrails daemon detected issues:\n${errors}\n`);
+      process.exit(2);
+    }
+  }
+} catch { /* ignore parse errors */ }
+
+process.exit(0);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-guardrails",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "mcpName": "io.github.logi-cmd/agent-guardrails",
   "description": "Production guardrails for AI coding agents",
   "type": "module",