@amsterdamdatalabs/enact-operator 0.1.2

package/runtime/hooks/tools/pre-tool-use.mjs

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+import { appendFileSync, existsSync as _existsSync, mkdirSync, readFileSync } from "node:fs";
+import { isAbsolute as _isAbsolute, resolve as _resolve } from "node:path";
+import { rootDirFrom } from "../shared/root-dir.mjs";
+import { layoutPath } from "../shared/layout-dir.mjs";
+import { readMergedOperatorConfig } from "../shared/config.mjs";
+import { emitHookFired, registerHookFailureTrap } from "../shared/observability.mjs";
+import { readHooksVerbose, verboseLog } from "../shared/_lib.mjs";
+
+function readStdin() {
+  try {
+    return JSON.parse(readFileSync(0, "utf8") || "{}");
+  } catch {
+    return {};
+  }
+}
+
+function readWorkspaceConfig(startDir = process.cwd()) {
+  return readMergedOperatorConfig(startDir);
+}
+
+const payload = readStdin();
+const startedAt = Date.now();
+const completeHook = registerHookFailureTrap({
+  payload,
+  hookEvent: "PreToolUse",
+  startedAt,
+  toolName: payload?.tool_name ?? "Bash",
+});
+const command =
+  payload?.tool_input?.command ||
+  payload?.tool_input?.input ||
+  payload?.command ||
+  "";
+
+const workspaceStartDir = payload?.cwd ?? process.cwd();
+const root = rootDirFrom(workspaceStartDir);
+mkdirSync(layoutPath(root, "logs"), { recursive: true });
+const logFile = layoutPath(root, "logs", "hooks.log");
+
+const toolName = payload?.tool_name ?? "";
+const isBashTool = toolName === "Bash";
+
+// ── Guard: bashFileReadGuard ──────────────────────────────────────────────────
+// Warns when the agent uses cat/head/tail on a single file with no pipe or
+// redirect — the Read tool provides line numbers and is preferred.
+// Translated from donor bash-file-read-guard.ts; Bash-tool only (no MCP bypass).
+const BASH_FILE_READ_PATTERNS = [
+  /^\s*cat\s+(?!-)[^\s|&;]+\s*$/,
+  /^\s*head\s+(-n\s+\d+\s+)?(?!-)[^\s|&;]+\s*$/,
+  /^\s*tail\s+(-n\s+\d+\s+)?(?!-)[^\s|&;]+\s*$/,
+];
+const bashFileReadWarning = isBashTool && BASH_FILE_READ_PATTERNS.some((p) => p.test(command))
+  ? "Prefer the Read tool over `cat`/`head`/`tail` for reading file contents. The Read tool provides line numbers and hash anchors for precise editing."
+  : null;
+
+// ── Guard: stderrHideWarning (non-blocking) ───────────────────────────────────
+// Advises against discarding stderr to /dev/null — silenced errors hide real
+// failures. This is a soft warning, NOT a block: the command still runs.
+// Matches `2>/dev/null`, `2> /dev/null`, and combined `>/dev/null 2>&1`.
+const stderrHideWarning = isBashTool && /2>\s*\/dev\/null|>\s*\/dev\/null\s+2>&1/.test(command)
+  ? "Avoid silencing stderr with `2>/dev/null` — discarded errors hide real failures. Keep stderr visible, or capture it to a file you can inspect."
+  : null;
+
+// Combine all non-blocking advisories into a single additionalContext string.
+const advisoryContext = [bashFileReadWarning, stderrHideWarning]
+  .filter(Boolean)
+  .join("\n\n") || null;
+
+// ── Guard: writeExistingFileGuard ─────────────────────────────────────────────
+// Blocks Bash-tool commands that would overwrite an existing file via shell
+// redirect (>), tee, or cp when the destination already exists on disk.
+// Translated from donor write-existing-file-guard/; Bash-tool only.
+//
+// Patterns detected:
+//   echo ... > FILE        (shell redirect to existing file)
+//   ... | tee FILE         (tee writing to existing file)
+//   cp SRC FILE            (cp overwriting existing file)
+function extractWriteDestination(cmd) {
+  // Shell redirect: anything before > then the target filename (not >>)
+  const redirectMatch = cmd.match(/(?:^|[^>])>\s*([^\s|&;>]+)/);
+  if (redirectMatch) {
+    const dest = redirectMatch[1].trim();
+    // /dev/null (and other /dev/* sinks) discard output — they are never
+    // "overwritten", so they must not trip the existing-file guard.
+    if (!/^\/dev\//.test(dest)) return dest;
+  }
+  // tee: tee <file> at end of pipeline
+  const teeMatch = cmd.match(/\btee\s+([^\s|&;]+)\s*$/);
+  if (teeMatch) return teeMatch[1].trim();
+  // cp: cp <src> <dest>
+  const cpMatch = cmd.match(/^\s*cp\s+(?:-\w+\s+)*(\S+)\s+(\S+)\s*$/);
+  if (cpMatch) return cpMatch[2].trim();
+  return null;
+}
+
+function resolveWritePath(dest, cwd) {
+  return _isAbsolute(dest) ? dest : _resolve(cwd, dest);
+}
+
+const writeExistingFileDeny = (() => {
+  if (!isBashTool) return false;
+  const dest = extractWriteDestination(command);
+  if (!dest) return false;
+  const abs = resolveWritePath(dest, workspaceStartDir);
+  return _existsSync(abs);
+})();
+
+// ── Guardrail 1: destructive shell commands ──────────────────────────────────
+const blocked = /\brm\s+-rf\b|\bgit\s+reset\s+--hard\b|\bgit\s+clean\s+-fd\b|\bDROP\s+TABLE\b|\bmkfs\b/i.test(command);
+
+// ── Guardrail 2: direct reads of Operator control-plane state ─────────────────
+//
+// Protected paths (have first-class MCP equivalents):
+//   .enact/operator/state/*.json          → operator_hud / operator_task_list / operator_state_read
+//   .enact/operator/sessions/current.json → operator_session_status
+//   .enact/operator/team/team.json        → operator_team_status
+//
+// NOT blocked: plans/, research/, reports/, logs/ (intentionally operator-readable)
+//
+// NOTE: This guard only fires for Bash tool events (matcher: 'Bash' in hooks.ts).
+// Non-Bash MCP file-read tools such as mcp__enact_ctx__ctx_read do NOT pass
+// through this hook — they bypass via the enact-context MCP server directly.
+// TODO(slice-2): Add path deny-list in the enact-context MCP server for the same
+// protected paths. See docs/a_proposed/2026-05-15-operator-direct-state-io-guardrail.md
+// "Non-Bash MCP File-Read Paths (Audit Conclusion)" section.
+
+// Matches cat/jq/sed/rg/grep/head/tail/awk/less/more used against one of the
+// three protected path tokens. Works with absolute and relative paths, with or
+// without surrounding quotes. Does NOT match plans/, research/, reports/, logs/.
+const STATE_IO_COMMANDS = /\b(cat|jq|sed|rg|grep|head|tail|awk|less|more)\b/i;
+const STATE_IO_PATHS = /(?:^|[\s|;&"'`(])(?:[^\s"'`]*[\\/])?\.enact[\\/]operator[\\/](?:state[\\/][^\s"'`]*\.json|sessions[\\/]current\.json|team[\\/]team\.json)/;
+const directStateRead = STATE_IO_COMMANDS.test(command) && STATE_IO_PATHS.test(command);
+
+// ── Read-only command detection (for task sync gate) ─────────────────────────
+// These patterns are safe to allow even when the sync gate is active.
+const READ_ONLY_COMMANDS = /^(ls|pwd|find|echo|wc|which|type|env|printenv|node\s+--version|pnpm\s+(list|ls)|npm\s+(list|ls)|git\s+(status|log|diff|show|branch|stash\s+list|remote|describe)|du\s|df\s|stat\s)/i;
+const isReadOnly = READ_ONLY_COMMANDS.test(command.trimStart());
+
+// ── Guardrail 3: task sync gate ───────────────────────────────────────────────
+// If the active lane has pending local tasks and no progress has been made
+// for >= LANE_SYNC_GATE_THRESHOLD turns, block mutating Bash commands.
+let taskSyncDeny = false;
+try {
+  if (!blocked && !directStateRead && !isReadOnly) {
+    const { readOperatorAuthority } = await import("@amsterdamdatalabs/enact-operator/authority");
+    const authority = readOperatorAuthority(root);
+    const hasActiveLane = !!(authority.ralph?.active || authority.ultrawork?.active || authority.autopilot?.active || authority.team?.active);
+    if (hasActiveLane) {
+    const { readContinuationState, buildContinuationGuidance, isLaneSyncGated } = await import("@amsterdamdatalabs/enact-operator/continuation");
+      const state = readContinuationState(root);
+      const guidance = buildContinuationGuidance(authority);
+      taskSyncDeny = isLaneSyncGated(state, guidance);
+    }
+  }
+} catch {
+  // best-effort: never block on gate read errors
+}
+
+appendFileSync(logFile, `${new Date().toISOString()} PreToolUse ${command}\n`, "utf8");
+
+if (blocked) {
+  await emitHookFired({
+    payload,
+    hookEvent: "PreToolUse",
+    outcome: "denied",
+    latencyMs: Date.now() - startedAt,
+    toolName: payload?.tool_name ?? "Bash",
+  });
+  completeHook();
+  process.stdout.write(JSON.stringify({
+    decision: "block",
+    reason: "Operator safety preset blocked an obviously destructive command.",
+  }));
+} else if (directStateRead) {
+const allowOverride = readWorkspaceConfig(workspaceStartDir)?.operator?.allow_direct_state_io === true;
+  if (allowOverride) {
+    appendFileSync(logFile, `${new Date().toISOString()} PreToolUse ESCAPE-HATCH operator.allow_direct_state_io used for: ${command}\n`, "utf8");
+    await emitHookFired({
+      payload,
+      hookEvent: "PreToolUse",
+      outcome: "allowed",
+      latencyMs: Date.now() - startedAt,
+      toolName: payload?.tool_name ?? "Bash",
+    });
+    completeHook();
+    process.stdout.write(JSON.stringify({ continue: true }));
+  } else {
+    await emitHookFired({
+      payload,
+      hookEvent: "PreToolUse",
+      outcome: "denied",
+      latencyMs: Date.now() - startedAt,
+      toolName: payload?.tool_name ?? "Bash",
+    });
+    completeHook();
+    process.stdout.write(JSON.stringify({
+      decision: "block",
+      reason:
+        "Direct shell reads of Operator control-plane state are not allowed. " +
+        "Use the Operator MCP surface instead:\n" +
+        "  • operator_hud            — summary runtime truth\n" +
+        "  • operator_session_status — session state (.enact/operator/sessions/current.json)\n" +
+        "  • operator_team_status    — team state (.enact/operator/team/team.json)\n" +
+        "  • operator_task_list      — local tasks\n" +
+        "  • operator_reviews_list   — reviews\n" +
+        "  • operator_inbox_list     — inbox\n" +
+        "  • operator_state_read     — named mode state (.enact/operator/state/*.json)\n" +
+        "To allow direct access for operator debugging, set [operator].allow_direct_state_io = true in config.toml.",
+    }));
+  }
+} else if (writeExistingFileDeny) {
+  await emitHookFired({
+    payload,
+    hookEvent: "PreToolUse",
+    outcome: "denied",
+    latencyMs: Date.now() - startedAt,
+    toolName: payload?.tool_name ?? "Bash",
+  });
+  completeHook({ blocked: true });
+  process.stdout.write(JSON.stringify({
+    decision: "block",
+    reason:
+      "writeExistingFileGuard: the destination file already exists. " +
+      "Use the Edit tool to modify existing files instead of overwriting them with shell redirects, tee, or cp. " +
+      "The Edit tool preserves history and avoids accidental data loss.",
+  }));
+} else if (taskSyncDeny) {
+  await emitHookFired({
+    payload,
+    hookEvent: "PreToolUse",
+    outcome: "denied",
+    latencyMs: Date.now() - startedAt,
+    toolName: payload?.tool_name ?? "Bash",
+  });
+  completeHook();
+  process.stdout.write(JSON.stringify({
+    decision: "block",
+    reason:
+      "Task sync gate: the active lane has pending local tasks and no progress has been recorded. " +
+      "Update the local task before running more commands.\n" +
+      "  1. operator_task_read   — read the pending local task\n" +
+      "  2. operator_task_update — record real status, notes, or blocker\n" +
+      "Read-only commands (ls, git status, git log, etc.) are still allowed.",
+  }));
+} else {
+  await emitHookFired({
+    payload,
+    hookEvent: "PreToolUse",
+    outcome: "allowed",
+    latencyMs: Date.now() - startedAt,
+    toolName: payload?.tool_name ?? "Bash",
+  });
+  completeHook();
+
+  if (readHooksVerbose(workspaceStartDir)) verboseLog("pre-tool-use", `allow — ${toolName || "tool"} passed through`);
+  if (advisoryContext) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: "PreToolUse",
+        permissionDecision: "allow",
+        additionalContext: advisoryContext,
+      },
+    }));
+  } else {
+    process.stdout.write(JSON.stringify({ continue: true }));
+  }
+}

package/runtime/hooks/user-prompt-submit.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+
+import "./lanes/user-prompt-submit.mjs";
+