cclaw-cli 0.48.33 → 0.48.35

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,9 @@ 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 configPath = join(runtimeDir, "config.yaml");
   const flowStatePath = join(stateDir, "flow-state.json");
   const checkpointPath = join(stateDir, "checkpoint.json");
   const activityPath = join(stateDir, "stage-activity.jsonl");
@@ -34,6 +37,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 +296,52 @@ 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);
+  }
+
+  /**
+   * A hook process can exit non-zero for two very different reasons:
+   *   (a) the guard legitimately decided to refuse an operation
+   *       (strict-mode refusal — this is the *only* case we ever want
+   *       to surface as a block to the user), or
+   *   (b) the hook infrastructure itself failed — the runtime crashed,
+   *       a child binary was missing, stderr is a chunk of yargs help
+   *       from some unrelated process, timeout, etc.
+   *
+   * Treating (b) as a block is what produces the "guard blocked
+   * tool.execute.before" error on a user who did nothing wrong. The
+   * heuristic below trims guaranteed-infra signals so only cleanly
+   * structured guard output is eligible for a real strict-mode block.
+   */
+  const INFRA_NOISE_PATTERNS = [
+    /^\\s*(Usage|Options|Commands|Examples|Positionals|Aliases):/im,
+    /^\\s*--[a-z][a-z0-9-]*\\b.*\\[(string|boolean|number|array)\\]/im,
+    /\\bcommand (not found|failed)\\b/i,
+    /\\bno such file or directory\\b/i,
+    /\\bCannot find module\\b/i,
+    /\\bThrowsCompletion\\b/,
+    /\\b(Reference|Syntax|Type|Range)Error\\b/,
+    /^\\s*at [^\\n]+\\([^)]*:\\d+:\\d+\\)/im,
+    /^\\s*node:internal\\b/im
+  ];
+  function looksLikeInfrastructureFailure(stderr) {
+    if (typeof stderr !== "string") return true;
+    const trimmed = stderr.trim();
+    if (trimmed.length === 0) return true;
+    for (const pattern of INFRA_NOISE_PATTERNS) {
+      if (pattern.test(trimmed)) return true;
+    }
+    return false;
+  }
+
   async function runHookScript(hookName, payload = {}) {
     const { spawn } = await import("node:child_process");
     const hookRuntimePath = join(root, "${RUNTIME_ROOT}/hooks/run-hook.mjs");
@@ -282,6 +352,7 @@ export default function cclawPlugin(ctx) {
       const finish = (ok) => {
         if (settled) return;
         settled = true;
+        recordHookStderr(hookName, stderr);
         resolve(ok);
       };
 
@@ -296,13 +367,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 +395,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 +432,182 @@ 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([
+    // Filesystem / search reads — no state mutation possible.
+    "read",
+    "glob",
+    "grep",
+    "list",
+    "ls",
+    "view",
+    "find",
+    // Network reads — no local state mutation.
+    "webfetch",
+    "websearch",
+    // User-facing question / ask tools: they only ask the human for
+    // input and cannot touch the filesystem or execute code. Blocking
+    // them strands the plugin mid-decision (see OpenCode's \`question\`).
+    "question",
+    "ask",
+    "askuser",
+    "askquestion",
+    "ask_question",
+    "ask_user",
+    "ask_user_question",
+    "askuserquestion",
+    "request_user_input",
+    "requestuserinput",
+    "prompt",
+    // Thinking / scratchpad tools — pure reasoning with no side effects.
+    "think",
+    "thinking",
+    // Todo bookkeeping tools — they write only inside the harness's own
+    // session state, not project files, and blocking them breaks agent
+    // planning without protecting anything.
+    "todo",
+    "todoread",
+    "todowrite",
+    "todo_read",
+    "todo_write"
+  ]);
+
+  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;
+  }
+
+  /**
+   * Strictness derived from (in order of precedence): CCLAW_STRICTNESS
+   * env override, \`.cclaw/config.yaml\` key \`strictness\`, or the
+   * library default of "advisory". The plugin only ever *blocks* tool
+   * execution when strictness resolves to "strict"; in advisory mode
+   * guard failures are logged and the tool call proceeds. This mirrors
+   * the Ralph-loop / hook-runtime semantics of
+   * \`DEFAULT_STRICTNESS = advisory\`, so the plugin can no longer
+   * accidentally be the stricter half of a mismatched pair.
+   */
+  function readConfigStrictness() {
+    try {
+      if (!existsSync(configPath)) return "";
+      const { readFileSync } = require("node:fs");
+      const raw = readFileSync(configPath, "utf8");
+      if (typeof raw !== "string" || raw.length === 0) return "";
+      const match = raw.match(/^\\s*strictness\\s*:\\s*([A-Za-z0-9_-]+)/m);
+      return match && typeof match[1] === "string" ? match[1].trim().toLowerCase() : "";
+    } catch {
+      return "";
+    }
+  }
+
+  function resolveStrictness() {
+    const envRaw = typeof process.env.CCLAW_STRICTNESS === "string"
+      ? process.env.CCLAW_STRICTNESS.trim().toLowerCase()
+      : "";
+    if (envRaw === "strict") return "strict";
+    if (envRaw === "advisory" || envRaw === "off" || envRaw === "disabled" || envRaw === "none") {
+      return "advisory";
+    }
+    const fileRaw = readConfigStrictness();
+    if (fileRaw === "strict") return "strict";
+    return "advisory";
+  }
+
+  /**
+   * 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 +660,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 +688,65 @@ 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)";
+        if (looksLikeInfrastructureFailure(rawDetail)) {
+          // Never let a broken hook runtime or misrouted child-process
+          // stderr (yargs help, Node crash, ENOENT, timeout) masquerade
+          // as a policy block. Log the infra hit and let the user keep
+          // working regardless of strictness.
+          logToFile(
+            "infra: " + failed + " non-zero exit with non-guard stderr — treated as infrastructure failure, tool allowed. " +
+            "stderr=" + detail.replace(/\\s+/g, " ").slice(0, 300)
+          );
+          return;
+        }
+        const strictness = resolveStrictness();
+        if (strictness !== "strict") {
+          // Advisory mode (the default) — every guard refusal is a hint,
+          // not a hard stop. Users report the "failure" as a log line
+          // and keep working. Only \`strictness: strict\` in config.yaml
+          // or CCLAW_STRICTNESS=strict upgrades this to a thrown block.
+          logToFile(
+            "advisory: " + failed + " flagged tool.execute.before (strictness=" +
+            strictness + "). detail=" + detail.replace(/\\s+/g, " ").slice(0, 300)
+          );
+          return;
+        }
         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,\\n" +
+          "or set \`strictness: advisory\` in .cclaw/config.yaml."
         );
       }
     },

package/package.json

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