cclaw-cli 0.48.33 → 0.48.34

package/dist/content/opencode-plugin.js

@@ -2,7 +2,7 @@ import { RUNTIME_ROOT } from "../constants.js";
 import { META_SKILL_NAME } from "./meta-skill.js";
 export function opencodePluginJs(_options = {}) {
     return `// cclaw OpenCode plugin — generated by cclaw sync
-import { existsSync, mkdirSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 
@@ -10,6 +10,8 @@ export default function cclawPlugin(ctx) {
   const root = ctx.directory || process.cwd();
   const runtimeDir = join(root, "${RUNTIME_ROOT}");
   const stateDir = join(runtimeDir, "state");
+  const logsDir = join(runtimeDir, "logs");
+  const pluginLogPath = join(logsDir, "opencode-plugin.log");
   const flowStatePath = join(stateDir, "flow-state.json");
   const checkpointPath = join(stateDir, "checkpoint.json");
   const activityPath = join(stateDir, "stage-activity.jsonl");
@@ -34,6 +36,27 @@ export default function cclawPlugin(ctx) {
     }
   }
 
+  /**
+   * Diagnostic log used instead of console.error on the hot path.
+   * Writing to a file keeps hook failures and unknown events from
+   * racing OpenCode's TUI renderer (which causes the overlapping-text
+   * artifact users have reported). Best-effort: any I/O failure is
+   * swallowed so logging never itself blocks or throws.
+   */
+  function logToFile(line) {
+    try {
+      mkdirSync(logsDir, { recursive: true });
+    } catch {
+      return;
+    }
+    const timestamp = new Date().toISOString();
+    try {
+      appendFileSync(pluginLogPath, timestamp + " " + line + "\\n", "utf8");
+    } catch {
+      // ignore — never let logging fail the hook
+    }
+  }
+
   async function readFlowState() {
     try {
       const raw = await readFile(flowStatePath, "utf8");
@@ -272,6 +295,17 @@ export default function cclawPlugin(ctx) {
     });
   }
 
+  const lastHookStderr = new Map();
+  function recordHookStderr(hookName, stderr) {
+    if (typeof hookName !== "string" || hookName.length === 0) return;
+    const trimmed = typeof stderr === "string" ? stderr.trim() : "";
+    if (trimmed.length === 0) {
+      lastHookStderr.delete(hookName);
+      return;
+    }
+    lastHookStderr.set(hookName, trimmed);
+  }
+
   async function runHookScript(hookName, payload = {}) {
     const { spawn } = await import("node:child_process");
     const hookRuntimePath = join(root, "${RUNTIME_ROOT}/hooks/run-hook.mjs");
@@ -282,6 +316,7 @@ export default function cclawPlugin(ctx) {
       const finish = (ok) => {
         if (settled) return;
         settled = true;
+        recordHookStderr(hookName, stderr);
         resolve(ok);
       };
 
@@ -296,13 +331,19 @@ export default function cclawPlugin(ctx) {
         return;
       }
 
+      // Tool.execute.before is a user-facing hot path: 20s is far too
+      // long to wait on a guard. 5s gives the hook real breathing room
+      // (typical runtime is well under 500ms) while capping the worst-
+      // case stall at a number the user will still tolerate.
       const timer = setTimeout(() => {
         child.kill("SIGKILL");
         if (stderr.length > 0) {
-          console.error("[cclaw] opencode hook timeout: " + hookName + " stderr=" + stderr.slice(-1200));
+          logToFile("hook timeout: " + hookName + " stderr=" + stderr.slice(-1200));
+        } else {
+          logToFile("hook timeout: " + hookName + " (no stderr)");
         }
         finish(false);
-      }, 20_000);
+      }, 5_000);
 
       child.stderr?.on("data", (chunk) => {
         stderr += String(chunk ?? "");
@@ -318,7 +359,7 @@ export default function cclawPlugin(ctx) {
         clearTimeout(timer);
         const ok = code === 0;
         if (!ok && stderr.length > 0) {
-          console.error("[cclaw] opencode hook failed: " + hookName + " stderr=" + stderr.slice(-1200));
+          logToFile("hook failed: " + hookName + " exit=" + code + " stderr=" + stderr.slice(-1200));
         }
         finish(ok);
       });
@@ -355,6 +396,118 @@ export default function cclawPlugin(ctx) {
     return { input: input ?? {}, output: output ?? {} };
   }
 
+  /**
+   * Read-only tools cannot mutate state or execute arbitrary code, so
+   * running prompt/workflow guards on them is pure overhead and — worse —
+   * surfaces a hard block when guards are misconfigured. OpenCode tool
+   * names vary (Claude/Codex use PascalCase; opencode-native often uses
+   * lowercase), so we normalize and match against a tight allow-list.
+   * Anything not in this list (bash, edit, write, patch, task, run, …)
+   * still runs through guards.
+   */
+  const SAFE_READONLY_TOOLS = new Set([
+    "read",
+    "glob",
+    "grep",
+    "list",
+    "ls",
+    "view",
+    "webfetch",
+    "websearch"
+  ]);
+
+  function isSafeReadOnlyTool(payload) {
+    if (!payload || typeof payload !== "object") return false;
+    const candidates = [
+      payload.tool,
+      payload.name,
+      payload.tool_name,
+      payload.toolName
+    ];
+    const inner = payload.input;
+    if (inner && typeof inner === "object") {
+      candidates.push(inner.tool, inner.name, inner.tool_name, inner.toolName);
+    }
+    for (const candidate of candidates) {
+      if (typeof candidate !== "string" || candidate.length === 0) continue;
+      if (SAFE_READONLY_TOOLS.has(candidate.toLowerCase())) return true;
+    }
+    return false;
+  }
+
+  /**
+   * cclaw considers itself "active" in a project when both the state
+   * file and the hook runtime script exist. If either is missing the
+   * plugin behaves as a no-op for guards — this project hasn't been
+   * initialized (or the install is corrupt) and blocking every tool
+   * call would strand the user.
+   */
+  function isCclawInitialized() {
+    try {
+      const hookRuntimePath = join(runtimeDir, "hooks/run-hook.mjs");
+      return existsSync(flowStatePath) && existsSync(hookRuntimePath);
+    } catch {
+      return false;
+    }
+  }
+
+  let notInitializedAdvised = false;
+  function noteNotInitialized() {
+    if (notInitializedAdvised) return;
+    notInitializedAdvised = true;
+    logToFile(
+      "guards skipped: cclaw is not initialized in this project. " +
+      "Run \`cclaw init\` in " + root + " to activate flow enforcement."
+    );
+  }
+
+  /**
+   * Escape hatch for a user stuck behind a misbehaving guard chain.
+   * Reads a small set of env vars that all mean "turn cclaw off for this
+   * session": CCLAW_DISABLE=1 (primary), CCLAW_STRICTNESS=off, or
+   * CCLAW_GUARDS=off. Anything truthy disables both guards and the
+   * advisory path. Logged once so users can confirm the bypass is in
+   * effect without cluttering the TUI.
+   */
+  const DISABLE_ENV_KEYS = ["CCLAW_DISABLE", "CCLAW_GUARDS", "CCLAW_STRICTNESS"];
+  let disabledAdvised = false;
+  function isCclawDisabled() {
+    for (const key of DISABLE_ENV_KEYS) {
+      const raw = process.env[key];
+      if (typeof raw !== "string") continue;
+      const value = raw.trim().toLowerCase();
+      if (value.length === 0) continue;
+      if (key === "CCLAW_STRICTNESS") {
+        if (value === "off" || value === "disabled" || value === "none") {
+          return { disabled: true, key, value };
+        }
+        continue;
+      }
+      if (
+        value === "1" ||
+        value === "true" ||
+        value === "yes" ||
+        value === "on" ||
+        value === "off" ||
+        value === "disabled"
+      ) {
+        if (key === "CCLAW_GUARDS" && (value === "on" || value === "true" || value === "yes" || value === "1")) {
+          continue;
+        }
+        return { disabled: true, key, value };
+      }
+    }
+    return { disabled: false, key: "", value: "" };
+  }
+  function noteDisabled(reason) {
+    if (disabledAdvised) return;
+    disabledAdvised = true;
+    logToFile(
+      "guards disabled by env " + reason.key + "=" + reason.value + ". " +
+      "All tool calls will pass through without prompt/workflow checks."
+    );
+  }
+
   function resolveEventType(payload) {
     if (typeof payload === "string") return payload;
     if (payload && typeof payload === "object") {
@@ -407,7 +560,7 @@ export default function cclawPlugin(ctx) {
           payload && typeof payload === "object"
             ? Object.keys(payload).slice(0, 10).join(", ")
             : typeof payload;
-        console.error("[cclaw] opencode unknown event payload keys: " + keys);
+        logToFile("unknown event payload keys: " + keys);
       }
       // session.compacted must run pre-compact BEFORE refreshing the bootstrap
       // cache, otherwise the injected system prompt still shows the pre-compact
@@ -435,12 +588,41 @@ export default function cclawPlugin(ctx) {
       }
     },
     "tool.execute.before": async (input, output) => {
+      const disabled = isCclawDisabled();
+      if (disabled.disabled) {
+        // Explicit user override (CCLAW_DISABLE=1 et al): stay fully out
+        // of the way. Any real problem with the guard chain should not
+        // prevent the user from unblocking themselves.
+        noteDisabled(disabled);
+        return;
+      }
       const payload = normalizeToolPayload(input, output);
-      const promptOk = await runHookScript("prompt-guard", payload);
-      const workflowOk = await runHookScript("workflow-guard", payload);
+      if (isSafeReadOnlyTool(payload)) {
+        // Read-only tools bypass guards — they cannot mutate state and
+        // blocking them gives users an unusable session when guards are
+        // misconfigured or cclaw isn't fully initialized.
+        return;
+      }
+      if (!isCclawInitialized()) {
+        // Project has no flow-state or hook runtime: cclaw isn't in use
+        // here. Never block the user's tools because of setup they didn't
+        // ask for. Surface a single advisory so they can notice.
+        noteNotInitialized();
+        return;
+      }
+      const [promptOk, workflowOk] = await Promise.all([
+        runHookScript("prompt-guard", payload),
+        runHookScript("workflow-guard", payload)
+      ]);
       if (!promptOk || !workflowOk) {
+        const failed = !promptOk ? "prompt-guard" : "workflow-guard";
+        const rawDetail = lastHookStderr.get(failed) || "";
+        const detail = rawDetail.length > 0 ? rawDetail.slice(-400) : "(no stderr captured)";
         throw new Error(
-          "cclaw OpenCode guard blocked tool.execute.before (prompt/workflow guard non-zero exit)."
+          "cclaw " + failed + " blocked tool.execute.before.\\n" +
+          "Reason: " + detail + "\\n" +
+          "Diagnose: run \`cclaw doctor\` in project root.\\n" +
+          "Bypass (temporary): export CCLAW_DISABLE=1 before starting OpenCode."
         );
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cclaw-cli",
-  "version": "0.48.33",
+  "version": "0.48.34",
   "description": "Installer-first flow toolkit for coding agents",
   "type": "module",
   "bin": {