@humwick/runner 0.0.0-stage → 0.130.0

package/plugins/claude/hooks/gate-run-guard.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# PreToolUse guard (#2834): steers project gate commands run via Bash/Monitor to relay_run.
+# FAIL-OPEN: the decision lives in gate-run-guard.ts (shared SDK gate classifier); every
+# precondition miss here (not relay-managed, read-only, no bun) exits 0 with no output.
+[ -n "${AGENT_RELAY_RUNNER_PORT:-}" ] || exit 0
+[ "${AGENT_RELAY_APPROVAL:-}" != "read-only" ] || exit 0
+command -v bun >/dev/null 2>&1 || exit 0
+HOOK_DIR="${CLAUDE_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}/hooks"
+exec bun "${HOOK_DIR}/gate-run-guard.ts" 2>/dev/null || exit 0

package/plugins/claude/hooks/gate-run-guard.ts

@@ -0,0 +1,237 @@
+// PreToolUse guard (#2834): a Bash/Monitor call that runs one of THIS project's own gates
+// (`iterate`, `delivery`, `gates[].command` in the session repo's land-gates.json) is denied with
+// a steer to `relay_run`. FAIL-OPEN: any doubt or error prints nothing and exits 0. Bundled to a
+// dependency-free .mjs for provisioned copies (scripts/build-claude-monitor.ts).
+import { resolve } from "node:path";
+import { classifyGateRun, lexCommandLine, unwrapGroupCommand, unwrapShellCommand } from "@humwick/sdk/gate-run-classify";
+import { findRepoLandGatesConfig, gateCommandsForCwd } from "@humwick/sdk/land-gates";
+import { trustedFlatCommand } from "./shell-trust";
+import { waitLoopDenial } from "./wait-loop-guard";
+
+// Past this the command is an embedded script, not a gate launch; skip parsing it.
+const MAX_COMMAND_CHARS = 64 * 1024;
+// Mirrors the classifier's own unwrap depth (sdk MAX_SHELL_UNWRAP_DEPTH).
+const MAX_UNWRAP_DEPTH = 2;
+
+const SETUP_COMMANDS = new Set(["cd", "pushd", "export", "set", "source", ".", "echo", "printf", "true"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/;
+const SHELL_BINARIES = new Set(["sh", "bash", "zsh", "dash", "ksh"]);
+// Shell flags that prevent execution; everything else (--login, -o, -l, unknown) still runs.
+const SHELL_NON_EXEC_LONG = new Set(["--help", "--version", "--dump-po-strings", "--dump-strings"]);
+// Env flags that prevent execution; everything else still runs.
+const ENV_NON_EXEC_LONG = new Set(["--help", "--version"]);
+const shellQuote = (word: string): string => (/^[\w@%+=:,./-]+$/.test(word) ? word : `'${word.replaceAll("'", "'\\''")}'`);
+
+/** The classifier reads only a gate's first segment, so a `cd x && gate` / `printf ok && gate` config would
+ *  turn the setup piece into a "gate". Reduce each configured gate to its first real command. */
+function normalizeGate(gate: string | undefined): string | undefined {
+  if (!gate) return gate;
+  const segments = lexCommandLine(gate).filter((words) => !SETUP_COMMANDS.has(words[0] ?? "") && !words.every((word) => ASSIGNMENT.test(word)));
+  return segments[0]?.map(shellQuote).join(" ");
+}
+
+const repoRootOf = (dir: string): string | undefined => findRepoLandGatesConfig(dir)?.repoRoot;
+
+/** True when a `cd`/`pushd` in the command, or in any shell wrapper layer the classifier peels, leaves the
+ *  session's project (or cannot be resolved): the gate, if any, runs elsewhere. */
+function leavesProject(command: string, cwd: string): boolean {
+  const home = repoRootOf(cwd);
+  let candidate: string | undefined = command;
+  for (let depth = 0; depth <= MAX_UNWRAP_DEPTH && candidate !== undefined; depth += 1) {
+    let dir = cwd;
+    for (const words of lexCommandLine(candidate)) {
+      if (words[0] !== "cd" && words[0] !== "pushd") continue;
+      const target = words.slice(1).find((word) => !word.startsWith("-") || word === "-");
+      if (!target || target === "-" || /^~|\$|`/.test(target)) return true;
+      dir = resolve(dir, target);
+      if (repoRootOf(dir) !== home) return true;
+    }
+    candidate = unwrapShellCommand(candidate) ?? unwrapGroupCommand(candidate);
+  }
+  return false;
+}
+
+// The shared classifier stays shell-grammar-unaware on purpose (heavy-lease callers), so shell edge cases
+// fail open HERE only (shell-trust.ts); checked on the raw text, so wrapper contents are covered too.
+
+const baseBinary = (word: string): string => (word.split("/").pop() ?? word).toLowerCase();
+
+// True when this layer's shell/env wrapper carries a KNOWN non-executing flag (-n,
+// --help/--version and the like). Inverted direction: unknown flags stay executing, so
+// `bash --login -c '<gate>'` and `bash -o pipefail -c '<gate>'` still deny.
+function wrapperHasNonExecutingOption(candidate: string): boolean {
+  const words = lexCommandLine(candidate)[0] ?? [];
+  let index = 0;
+  while (index < words.length && ASSIGNMENT.test(words[index]!)) index += 1;
+  const binary = baseBinary(words[index] ?? "");
+  if (SHELL_BINARIES.has(binary)) {
+    for (let i = index + 1; i < words.length; i += 1) {
+      const flag = words[i]!;
+      if (!flag.startsWith("-") || flag === "--") break;
+      if (flag.startsWith("--")) {
+        if (SHELL_NON_EXEC_LONG.has(flag.split("=", 2)[0]!)) return true;
+        continue;
+      }
+      if (flag.includes("n")) return true;
+      if (/^-[a-z]*c$/.test(flag)) break;
+    }
+    return false;
+  }
+  if (binary === "env") {
+    for (let i = index + 1; i < words.length; i += 1) {
+      const flag = words[i]!;
+      if (!flag.startsWith("-") || flag === "--") break;
+      if (flag.startsWith("--") && ENV_NON_EXEC_LONG.has(flag.split("=", 2)[0]!)) return true;
+    }
+  }
+  return false;
+}
+
+// True when a quoted `-c` script is followed by a trailing PLAIN word (`bash -c '…' _ …'):
+// that word becomes `$0` data, not executed. Redirections, pipes, `;` and `&` after the
+// script are outer-command syntax, not operands, so they still deny. Unquoted scripts are
+// left to the classifier (joining them is its documented conservative choice).
+function shellHasExtraOperands(candidate: string): boolean {
+  const match = /^\s*(?:\S+\/)?(sh|bash|zsh|dash|ksh)\s+([\s\S]*)$/i.exec(candidate);
+  if (!match) return false;
+  let rest = match[2]!;
+  for (let guard = 0; guard < 16; guard += 1) {
+    rest = rest.replace(/^\s+/, "");
+    const flag = /^\S+/.exec(rest)?.[0];
+    if (!flag || !flag.startsWith("-")) return false;
+    rest = rest.slice(flag.length);
+    if (/^-[a-z]*c$/.test(flag)) break;
+    if (!rest.trim()) return false;
+  }
+  rest = rest.replace(/^\s+/, "");
+  const quote = rest[0];
+  if (quote !== "'" && quote !== '"') return false;
+  let i = 1;
+  while (i < rest.length && rest[i] !== quote) i += 1;
+  if (i >= rest.length) return false;
+  const after = rest.slice(i + 1).replace(/^\s+/, "");
+  if (!after) return false;
+  return !/^(?:\d*\s*[><|;&#])/.test(after);
+}
+
+// Fail open only when the gate sits on the dead side of a literal short-circuit:
+// `false && gate` and `true || gate` never run it. A gate on the live side (`gate ||
+// echo`, `gate && echo done`) still denies, as do `true && gate` and `false || gate`.
+function layerHasShortCircuit(candidate: string): boolean {
+  const parts: Array<{ text: string; op: string | null }> = [];
+  let current = "";
+  let inSingle = false;
+  let inDouble = false;
+  let pendingOp: string | null = null;
+  const push = (): void => {
+    parts.push({ text: current, op: pendingOp });
+    pendingOp = null;
+    current = "";
+  };
+  for (let i = 0; i < candidate.length; i += 1) {
+    const char = candidate[i]!;
+    if (inSingle) { current += char; if (char === "'") inSingle = false; continue; }
+    if (inDouble) {
+      current += char;
+      if (char === "\\") { i += 1; if (i < candidate.length) current += candidate[i]; continue; }
+      if (char === '"') inDouble = false;
+      continue;
+    }
+    if (char === "\\") { current += char; i += 1; if (i < candidate.length) current += candidate[i]; continue; }
+    if (char === "'") { inSingle = true; current += char; continue; }
+    if (char === '"') { inDouble = true; current += char; continue; }
+    if (char === "&" && candidate[i + 1] === "&") { push(); pendingOp = "&&"; i += 1; continue; }
+    if (char === "|" && candidate[i + 1] === "|") { push(); pendingOp = "||"; i += 1; continue; }
+    current += char;
+  }
+  push();
+  // The command deciding the previous part is its last `;`-segment's binary, past assignments.
+  const decidingBinary = (text: string): string | undefined => {
+    const words = lexCommandLine(text).at(-1) ?? [];
+    return words.find((word) => !ASSIGNMENT.test(word));
+  };
+  for (let j = 1; j < parts.length; j += 1) {
+    const prev = decidingBinary(parts[j - 1]!.text);
+    if (parts[j]!.op === "&&" && prev === "false") return true;
+    if (parts[j]!.op === "||" && prev === "true") return true;
+  }
+  return false;
+}
+
+// Strip `-o/-O <name>` (and `+` variants) pairs from a shell wrapper's flag run. The shared
+// unwrap stops at the operand, so `bash -o pipefail -c '<gate>'` never peels; `-o` only sets
+// shell options, so dropping the pair is faithful. Exact reconstruction when nothing drops.
+function dropShellOptionOperands(command: string): string {
+  const match = /^\s*(?:\S+\/)?(?:sh|bash|zsh|dash|ksh)\s+([\s\S]*)$/i.exec(command);
+  if (!match) return command;
+  const regionStart = command.length - match[1]!.length;
+  let rest = match[1]!;
+  let kept = "";
+  for (let guard = 0; guard < 16; guard += 1) {
+    const trimmed = rest.replace(/^\s+/, "");
+    const word = /^\S+/.exec(trimmed)?.[0];
+    if (!word || word[0] === "'" || word[0] === '"') return command;
+    if (/^[-+][oO]$/.test(word)) {
+      const operand = /^[^\s&|;#]+/.exec(trimmed.slice(word.length).replace(/^\s+/, ""))?.[0];
+      if (!operand || operand[0] === "'" || operand[0] === '"') return command;
+      rest = trimmed.slice(word.length).replace(/^\s+/, "").slice(operand.length);
+      continue;
+    }
+    kept += rest.slice(0, rest.length - trimmed.length + word.length);
+    rest = trimmed.slice(word.length);
+    if (/^-[a-z]*c$/.test(word)) break;
+    if (!word.startsWith("-") && !word.startsWith("+")) break;
+  }
+  return command.slice(0, regionStart) + kept + rest;
+}
+
+// #2843 fail-opens, hook only: the shared classifier is unchanged (heavy-lease callers keep
+// its conservative join/short-circuit behavior). Each layer is checked, so wrapped forms
+// (`bash -lc 'false && gate'`, `bash -lc 'env --help gate'`) fail open through the wrapper.
+function failOpenForContrivedForm(flat: string): boolean {
+  let candidate: string | undefined = flat;
+  for (let depth = 0; depth <= MAX_UNWRAP_DEPTH && candidate !== undefined; depth += 1) {
+    if (wrapperHasNonExecutingOption(candidate)) return true;
+    if (shellHasExtraOperands(candidate)) return true;
+    if (layerHasShortCircuit(candidate)) return true;
+    candidate = unwrapShellCommand(candidate) ?? unwrapGroupCommand(candidate);
+  }
+  return false;
+}
+
+function gateDenial(command: string, flat: string, cwd: string): string | null {
+  const configured = gateCommandsForCwd(cwd);
+  const commands = {
+    iterate: normalizeGate(configured.iterate),
+    delivery: normalizeGate(configured.delivery),
+    gates: (configured.gates ?? []).map(normalizeGate).filter((gate): gate is string => Boolean(gate)),
+  };
+  if (!commands.iterate && !commands.delivery && !commands.gates?.length) return null;
+  const normalized = dropShellOptionOperands(flat);
+  if (failOpenForContrivedForm(normalized)) return null;
+  const category = classifyGateRun(normalized, commands);
+  if (!category || category === "heuristic") return null;
+  if (leavesProject(normalized, cwd)) return null;
+  return `This is a project gate: run it with the relay_run MCP tool (waitMs: 0), then end your turn; Relay wakes you once when it finishes. Command: ${command}`;
+}
+
+function decide(payload: unknown): string | null {
+  const input = payload as { tool_name?: unknown; tool_input?: { command?: unknown; run_in_background?: unknown }; cwd?: unknown } | null;
+  if (input?.tool_name !== "Bash" && input?.tool_name !== "Monitor") return null;
+  const command = input.tool_input?.command;
+  if (typeof command !== "string" || !command || command.length > MAX_COMMAND_CHARS) return null;
+  const cwd = typeof input.cwd === "string" && input.cwd ? input.cwd : process.cwd();
+  const flat = trustedFlatCommand(command);
+  const gate = flat === null ? null : gateDenial(command, flat, cwd);
+  // A harness-backgrounded Bash already returns the turn, so only foreground waits are redirected (#2993).
+  return gate ?? (input.tool_input?.run_in_background === true ? null : waitLoopDenial(command));
+}
+
+try {
+  const reason = decide(JSON.parse(await Bun.stdin.text()));
+  if (reason) {
+    console.log(JSON.stringify({ hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } }));
+  }
+} catch {
+  // fail open
+}

package/plugins/claude/hooks/hooks.json

@@ -0,0 +1,158 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/user-prompt-submit.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/read-only-bash-guard.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "Bash|Monitor",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/gate-run-guard.sh\"",
+            "timeout": 5
+          }
+        ]
+      },
+      {
+        "matcher": "AskUserQuestion",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/permission-request.sh\"",
+            "timeout": 900
+          }
+        ]
+      }
+    ],
+    "PermissionRequest": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/permission-request.sh\"",
+            "timeout": 900
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/stop.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "StopFailure": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/stop-failure.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-start.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/subagent-stop.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/pre-compact.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/post-compact.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-end.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Read|Edit|MultiEdit|Write|NotebookEdit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/post-tool-use.sh\"",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}