@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/admin/hooks/pre-tool-use.sh

@@ -0,0 +1,294 @@
+#!/usr/bin/env bash
+# PreToolUse hook — enforces agent tool boundaries and approval gating.
+# Usage: pre-tool-use.sh <agent-type>
+# Receives tool call JSON on stdin (from Claude Code hook protocol).
+# Exit 0 = allow, exit 2 = block.
+
+set -uo pipefail
+
+AGENT_TYPE="${1:-public}"
+
+# Read stdin — fail closed if unavailable
+if [ -t 0 ]; then
+  echo "Blocked: Cannot determine tool call (no stdin). Failing closed." >&2
+  exit 2
+fi
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | grep -o '"tool_name":"[^"]*"' | head -1 | cut -d'"' -f4)
+
+# ---------------------------------------------------------------------------
+# Admin agent — code directory protection + approval gating
+# ---------------------------------------------------------------------------
+if [ "$AGENT_TYPE" = "admin" ]; then
+
+  # ── Code directory protection ────────────────────────────────────────────
+  case "$TOOL_NAME" in
+    Write|Edit)
+      FILE_PATH=$(echo "$INPUT" | grep -o '"file_path":"[^"]*"' | head -1 | cut -d'"' -f4)
+      case "$FILE_PATH" in
+        # Platform UI source (platform/ui/) — source lives here, not on device
+        */platform/ui/app/*|*/platform/ui/lib/*|*/platform/ui/*.ts|*/platform/ui/*.tsx|*/platform/ui/*.mjs)
+          echo "Blocked: Admin agent cannot modify platform UI source at $FILE_PATH" >&2
+          exit 2
+          ;;
+        # Compiled MCP servers, hooks, and scripts — what actually ships to device
+        */platform/plugins/*/mcp/dist/*|*/platform/plugins/*/hooks/*|*/platform/scripts/*)
+          echo "Blocked: Admin agent cannot modify platform code at $FILE_PATH" >&2
+          exit 2
+          ;;
+        # Entitlement library (Task 831) — verifier source, compiled output, vendored
+        # pubkey, hash file, and any signed entitlement.json. Tampering here is the
+        # agent path to revenue bypass; the legitimate write path is the Rubytech
+        # issuance endpoint, never the agent's filesystem.
+        # Patterns intentionally cover both absolute (*/...) and relative
+        # (no leading slash) paths so an agent can't bypass via cwd-relative writes.
+        */platform/lib/entitlement/*|platform/lib/entitlement/*|*/entitlement.json|entitlement.json)
+          echo "Blocked: Admin agent cannot modify entitlement files at $FILE_PATH. Effective tier and purchasedPlugins derive from a Rubytech-signed payload." >&2
+          echo "[entitlement] tool-deny: tool=${TOOL_NAME} path=${FILE_PATH} field=entitlement-file" >&2
+          exit 2
+          ;;
+        # account.json (Task 831 + Task 850) — agent must use the account-update
+        # MCP tool (or plugin-toggle-enabled for enabledPlugins changes), which
+        # whitelists editable fields server-side. Direct Edit/Write bypasses
+        # that whitelist; deny unconditionally including cwd-relative paths.
+        # Task 850 adds */account.json and *account.json as a backstop so any
+        # layout the named patterns miss is still caught — the Adam Mackay
+        # incident showed a tier upgrade via raw Edit on account.json reach
+        # the disk, exactly the failure mode this hook exists to prevent.
+        */data/accounts/*/account.json|*/config/accounts/*/account.json|data/accounts/*/account.json|config/accounts/*/account.json|*/account.json|*account.json|account.json)
+          echo "Blocked: Admin agent cannot edit account.json directly. Use the account-update or plugin-toggle-enabled MCP tools — they whitelist editable fields server-side and exclude tier and purchasedPlugins by design." >&2
+          echo "[entitlement] tool-deny: tool=${TOOL_NAME} path=${FILE_PATH} field=account-json" >&2
+          exit 2
+          ;;
+        # Pending action queue — only the hook and MCP tools may write here
+        */pending-actions/*)
+          echo "Blocked: Admin agent cannot modify pending action files directly" >&2
+          exit 2
+          ;;
+      esac
+      ;;
+    Bash)
+      # Block shell commands referencing protected code directories or pending actions
+      case "$INPUT" in
+        *"platform/ui/app/"*|*"platform/ui/lib/"*|*"platform/plugins/"*"hooks/"*|*"platform/scripts/"*)
+          echo "Blocked: Admin agent cannot run shell commands against code directories" >&2
+          exit 2
+          ;;
+        # Entitlement files via shell (Task 831) — same surface, blocked symmetrically
+        *"platform/lib/entitlement/"*|*"entitlement.json"*)
+          echo "Blocked: Admin agent cannot reference entitlement files via shell." >&2
+          echo "[entitlement] tool-deny: tool=Bash path=entitlement-file field=entitlement-file" >&2
+          exit 2
+          ;;
+        # account.json via shell (Task 831) — same rationale as Edit/Write block
+        *"data/accounts/"*"account.json"*|*"config/accounts/"*"account.json"*)
+          echo "Blocked: Admin agent cannot edit account.json via shell. Use the account-update MCP tool." >&2
+          echo "[entitlement] tool-deny: tool=Bash path=account-json field=account-json" >&2
+          exit 2
+          ;;
+        *"pending-actions/"*)
+          echo "Blocked: Admin agent cannot modify pending action files via shell" >&2
+          exit 2
+          ;;
+      esac
+      ;;
+  esac
+
+  # ── Base64 context-overflow guard (Task 983) ─────────────────────────────
+  # Block inline base64 payloads from reaching the model context. Two paths:
+  #
+  #   1. Bash command that ENCODES a binary file to base64/hex (the producer).
+  #   2. Write/Edit content carrying an inline `data:<mime>;base64,…` blob
+  #      (the consumer — agent quoting bytes from a prior tool_result into a
+  #      HTML/markdown Write).
+  #
+  # Either path landed ~33 KB of base64 in the SDK request and the next turn
+  # tripped `main_stream_stalled` at 180 s (see Task 983 reproduction). The
+  # remediation is symmetric: the agent saves bytes to `$ACCOUNT_DIR/tmp/<sha1>.<ext>`
+  # and references the path (`<img src="./file">` or Read-by-path) instead of
+  # carrying bytes through the assistant turn.
+  #
+  # Parsing uses python3 (already a hook dependency at the action-id site
+  # below); grep on JSON is unsafe for content with escaped quotes or
+  # embedded newlines. Parse failure is fail-open (empty extracted string,
+  # no match, allow) — matches the playwright-file-guard fail-open contract.
+  # Single python3 invocation parses the JSON, runs the tool-specific
+  # regex match (avoiding BSD-vs-GNU grep interval-count incompatibilities —
+  # `grep -E '{4096,}'` errors with "invalid repetition count(s)" on macOS
+  # BSD grep under some pattern combinations), and prints the rejection
+  # outcome to stdout as `REJECT:<reason>:<bytes>` or `ALLOW`. The wrapping
+  # bash logic reads the verdict and emits the rejection log/stderr/exit-2.
+  # Parse failure prints `ALLOW` (fail-open, matching the playwright-file-
+  # guard contract for malformed stdin).
+  GUARD_VERDICT=$(echo "$INPUT" | python3 -c '
+import sys, json, re
+try:
+    d = json.load(sys.stdin)
+    tool = d.get("tool_name", "")
+    ti = d.get("tool_input", {}) or {}
+    if tool in ("Write", "Edit"):
+        # Write.content OR Edit.new_string can carry inline base64.
+        content = ti.get("content") or ti.get("new_string") or ""
+        if not isinstance(content, str):
+            print("ALLOW"); sys.exit(0)
+        # data:<mime>;base64,<≥4096 base64 chars> — threshold matches the
+        # doctrine paragraph in .docs/agents.md. The 4096-char body is
+        # ~3 KB binary, far above any legitimate inline icon.
+        m = re.search(r"data:[^;]+;base64,[A-Za-z0-9+/]{4096,}={0,2}", content)
+        if m:
+            print(f"REJECT:base64-write-content:{len(content)}")
+        else:
+            print("ALLOW")
+    elif tool == "Bash":
+        command = ti.get("command", "")
+        if not isinstance(command, str):
+            print("ALLOW"); sys.exit(0)
+        # Per-segment scan. A compound command like
+        #   cat in.b64 | base64 -d > out.bin; cat photo.png | base64
+        # contains both a legitimate decode AND a malicious encoder. A whole-
+        # command decode-flag check is fooled into allowing the encoder. Split
+        # on shell separators (;, &&, ||, &) and scan each segment as its own
+        # command — the encoder rejection fires when ANY segment is a bare
+        # base64 invocation without a paired decode flag in the SAME segment.
+        # Pipelines (|) keep the segment together because the encoder direction
+        # of `cat file | base64` lives across the pipe.
+        segments = re.split(r";|&&|\|\||(?<![|&])&(?![|&])", command)
+        rejected = None
+        for seg in segments:
+            if re.search(r"(?:^|[\s|;&])xxd[\t ]+-p(?![A-Za-z0-9_-])", seg):
+                rejected = "xxd-plain-hex"; break
+            if re.search(r"(?:^|[\s|;&])base64(?![A-Za-z0-9_-])", seg):
+                if not re.search(r"base64[\t ]+[^|]*(?:-d|-D|--decode)(?![A-Za-z0-9_])", seg):
+                    rejected = "base64-encoder"; break
+        if rejected:
+            print(f"REJECT:{rejected}:{len(command)}")
+        else:
+            print("ALLOW")
+    else:
+        print("ALLOW")
+except Exception:
+    print("ALLOW")
+' 2>/dev/null || echo "ALLOW")
+  case "$GUARD_VERDICT" in
+    REJECT:base64-write-content:*)
+      BYTES="${GUARD_VERDICT##*:}"
+      echo "[pre-tool-use] guard=base64-write-content bytes=${BYTES} action=reject" >&2
+      echo "Blocked: ${TOOL_NAME} content carries an inline base64 payload (>4 KB encoded). Inline binary in Write.content overloads the model context — the same path produced a main_stream_stalled at ~33 KB on 2026-05-09." >&2
+      echo "Save the bytes to \$ACCOUNT_DIR/tmp/<sha1>.<ext> via Bash (e.g. 'base64 -d > out.png'), then reference the file from the document: <img src=\"./<file>\"> or Read-by-path. Do not carry binary bytes through the assistant turn." >&2
+      exit 2
+      ;;
+    REJECT:base64-encoder:*|REJECT:xxd-plain-hex:*)
+      REASON="${GUARD_VERDICT#REJECT:}"; REASON="${REASON%:*}"
+      BYTES="${GUARD_VERDICT##*:}"
+      echo "[pre-tool-use] guard=base64-tool-result bytes=${BYTES} tool=Bash reason=${REASON} action=reject" >&2
+      echo "Blocked: Bash command would emit binary as inline base64/hex to stdout, which lands in the assistant turn and overloads the model context (the 2026-05-09 Rubytech-invoice path hit 66% context after a single ~33 KB tool_result)." >&2
+      echo "Instead: save the bytes directly to \$ACCOUNT_DIR/tmp/<sha1>.<ext> and operate on the file via path — Read for inspection, <img src=\"./<file>\"> for HTML embedding, file-attach for delivery. Decoding base64 (e.g. 'base64 -d in.b64 > out.bin') is allowed." >&2
+      exit 2
+      ;;
+    *)
+      : # ALLOW — fall through to approval gating below
+      ;;
+  esac
+
+  # ── Approval gating (EU AI Act Article 14 — human oversight) ─────────────
+  # Strip the mcp__<plugin>__ prefix to get the short tool name.
+  # Built-in tools (no prefix) pass through unchanged.
+  SHORT_NAME=$(echo "$TOOL_NAME" | sed 's/^mcp__[^_]*__//')
+
+  # Derive platform root from this hook's location:
+  #   platform/plugins/admin/hooks/pre-tool-use.sh → platform/
+  HOOK_DIR="$(cd "$(dirname "$0")" 2>/dev/null && pwd)"
+  PLATFORM_ROOT="${HOOK_DIR}/../../.."
+
+  # Resolve the single account directory (Phase 0).
+  ACCOUNTS_DIR="${PLATFORM_ROOT}/../data/accounts"
+  ACCOUNT_DIR=""
+  if [ -d "$ACCOUNTS_DIR" ]; then
+    ACCOUNT_DIR=$(find "$ACCOUNTS_DIR" -mindepth 1 -maxdepth 1 -type d 2>/dev/null | head -1)
+  fi
+
+  # Default require-review tools — matches DEFAULT_REQUIRE_REVIEW in claude-agent.ts
+  DEFAULT_REQUIRE_REVIEW="email-send email-reply whatsapp-send whatsapp-send-document message contact-erase"
+
+  # Check if this tool requires approval review.
+  # 1. Read per-account override from account.json approvalPolicy (if it exists)
+  # 2. Fall back to the default require-review list
+  POLICY=""
+  if [ -n "$ACCOUNT_DIR" ] && [ -f "${ACCOUNT_DIR}/account.json" ]; then
+    # Check per-account override first (grep for the tool name in the approvalPolicy block)
+    OVERRIDE=$(grep -o "\"${SHORT_NAME}\"[[:space:]]*:[[:space:]]*\"[^\"]*\"" "${ACCOUNT_DIR}/account.json" 2>/dev/null | head -1 | grep -o '"[^"]*"$' | tr -d '"')
+    if [ -n "$OVERRIDE" ]; then
+      POLICY="$OVERRIDE"
+    fi
+  fi
+
+  # If no per-account override, check the default list
+  if [ -z "$POLICY" ]; then
+    for TOOL in $DEFAULT_REQUIRE_REVIEW; do
+      if [ "$SHORT_NAME" = "$TOOL" ]; then
+        POLICY="require-review"
+        break
+      fi
+    done
+  fi
+
+  # If not in any policy, auto-execute (allow)
+  if [ "$POLICY" != "require-review" ]; then
+    exit 0
+  fi
+
+  # ── Special case: contact-erase preview calls pass through ───────────────
+  # The contact-erase tool has a two-step flow: first call with confirm:false
+  # returns a preview (data counts), second call with confirm:true executes.
+  # Only gate the destructive confirm:true call.
+  if [ "$SHORT_NAME" = "contact-erase" ]; then
+    if ! echo "$INPUT" | grep -q '"confirm"[[:space:]]*:[[:space:]]*true'; then
+      exit 0
+    fi
+  fi
+
+  # ── Queue the action for approval ───────────────────────────────────────
+  PENDING_DIR="${ACCOUNT_DIR}/pending-actions"
+  mkdir -p "$PENDING_DIR" 2>/dev/null
+
+  ACTION_ID="$(cat /proc/sys/kernel/random/uuid 2>/dev/null || python3 -c 'import uuid; print(uuid.uuid4())' 2>/dev/null || date +%s%N)"
+  CREATED_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+
+  # Write atomically: temp file + mv
+  TEMP=$(mktemp "${PENDING_DIR}/.tmp.XXXXXX" 2>/dev/null)
+  if [ -z "$TEMP" ]; then
+    echo "Blocked: Action requires approval but failed to create queue file (disk error). Failing closed." >&2
+    exit 2
+  fi
+
+  # The pending action file contains the full hook JSON (tool_name + tool_input)
+  # plus metadata. The MCP approval tools parse it with Node.js JSON.parse.
+  cat > "$TEMP" <<ENDJSON
+{
+  "actionId": "${ACTION_ID}",
+  "toolName": "${SHORT_NAME}",
+  "pluginName": "$(echo "$TOOL_NAME" | sed -n 's/^mcp__\([^_]*\)__.*/\1/p')",
+  "hookPayload": ${INPUT},
+  "state": "pending",
+  "createdAt": "${CREATED_AT}"
+}
+ENDJSON
+
+  if ! mv "$TEMP" "${PENDING_DIR}/${ACTION_ID}.json" 2>/dev/null; then
+    rm -f "$TEMP" 2>/dev/null
+    echo "Blocked: Action requires approval but failed to queue (filesystem error). Failing closed." >&2
+    exit 2
+  fi
+
+  # Extract a readable summary of the action for the agent to present
+  # tool_input is the second JSON value in the hook payload
+  echo "Action requires approval before execution."
+  echo ""
+  echo "Action ID: ${ACTION_ID}"
+  echo "Tool: ${SHORT_NAME}"
+  echo "Status: Queued for review"
+  echo ""
+  echo "The admin must approve this action before it can execute."
+  echo "Use action-approve to send, action-reject to cancel, or action-edit to modify."
+  exit 2
+fi

package/payload/platform/plugins/admin/hooks/webfetch-preflight.mjs

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+// PreToolUse hook for WebFetch — detects JS-SPA shells before Claude Code's
+// internal extraction pipeline burns its 60-second axios timeout on an HTML
+// shell that has no server-rendered content. WebFetch is HTTP-only — when it
+// gets a body like `<div id="root"></div>` plus a single `<script>`, there
+// is nothing to extract, and waiting 60s changes nothing.
+//
+// Wired in account_settings.json hooks.PreToolUse[matcher=WebFetch] (see
+// platform/scripts/seed-neo4j.sh). Reads Claude Code hook protocol JSON on
+// stdin: { tool_name, tool_input: { url, prompt } }.
+//
+// Outcomes:
+//   spa-shell    → exit 2, stderr = WEBFETCH_CANNOT_READ_JS_SPA: <directive>
+//                  Claude Code synthesises a tool_result with is_error=true
+//                  and stderr as content, the agent surfaces a loud failure
+//                  to the user (per IDENTITY.md "Tool Failure Discipline").
+//   ok           → exit 0, allow the real WebFetch to run.
+//   inconclusive → exit 0, allow the real WebFetch to run. Anything that
+//                  isn't a high-confidence positive shell detection passes
+//                  through — fail-open is the only safe posture for a
+//                  preflight gate. Blocking false positives would be worse
+//                  than the 60-second stall this hook exists to prevent.
+//
+// Every branch writes one verdict line to
+// ${ACCOUNT_DIR}/logs/webfetch-preflight.log so the decision trail is
+// retrievable per-account without correlating across conversation logs.
+//
+// Cache: ${ACCOUNT_DIR}/cache/webfetch-preflight/<sha256(url)>.json with
+// a 10-minute mtime TTL. The verdict is intrinsic to the URL's response
+// shape, not to any conversation's context — account-scoped sharing
+// eliminates duplicate probes when the same URL recurs across sessions.
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync, statSync, appendFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+
+const PROBE_TIMEOUT_MS = 2000;
+const MAX_BODY_BYTES = 64 * 1024;
+const CACHE_TTL_MS = 10 * 60 * 1000;
+const SHELL_BYTE_THRESHOLD = 5 * 1024;
+const TEXT_BYTE_THRESHOLD = 20;
+
+const accountDir = process.env.ACCOUNT_DIR || "";
+const logPath = accountDir ? resolve(accountDir, "logs", "webfetch-preflight.log") : null;
+
+function ts() {
+  return new Date().toISOString();
+}
+
+function logLine(line) {
+  if (!logPath) return;
+  try {
+    mkdirSync(dirname(logPath), { recursive: true });
+    appendFileSync(logPath, `[${ts()}] ${line}\n`);
+  } catch {
+    // Logging failure must never block the tool. The verdict still emits to
+    // stderr where Claude Code's own hook-stderr capture will catch it.
+  }
+}
+
+function emitVerdict(fields, allowFlag) {
+  const line = `[webfetch-preflight] ${fields.join(" ")}`;
+  logLine(line);
+  // Stderr trail so a reader inspecting Claude Code's hook stderr capture
+  // sees the same verdict line (independent of the per-account log file).
+  process.stderr.write(line + "\n");
+  if (allowFlag === "block") {
+    // Caller adds the structured WEBFETCH_CANNOT_READ_JS_SPA message before
+    // exiting — this function only emits the diagnostic line.
+    return;
+  }
+  process.exit(0);
+}
+
+async function readStdin() {
+  return new Promise((resolvePromise, rejectPromise) => {
+    const chunks = [];
+    let total = 0;
+    const limit = 64 * 1024;
+    process.stdin.on("data", (c) => {
+      chunks.push(c);
+      total += c.length;
+      if (total > limit) {
+        // Destroy the stream before rejecting so the `end` listener can't fire
+        // a no-op resolve on the rejected Promise (and so we don't allocate
+        // a large Buffer.concat over already-discarded chunks).
+        process.stdin.destroy();
+        rejectPromise(new Error("stdin-too-large"));
+      }
+    });
+    process.stdin.on("end", () => resolvePromise(Buffer.concat(chunks).toString("utf8")));
+    process.stdin.on("error", rejectPromise);
+  });
+}
+
+function readBodyCapped(res, maxBytes) {
+  return new Promise(async (resolvePromise, rejectPromise) => {
+    try {
+      const reader = res.body.getReader();
+      const chunks = [];
+      let total = 0;
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        chunks.push(Buffer.from(value));
+        total += value.byteLength;
+        if (total >= maxBytes) {
+          reader.cancel().catch(() => {});
+          break;
+        }
+      }
+      resolvePromise(Buffer.concat(chunks, Math.min(total, maxBytes)));
+    } catch (err) {
+      rejectPromise(err);
+    }
+  });
+}
+
+function detectShape(bodyStr) {
+  // Strip <script>, <style>, comments, then all tags. What remains is the
+  // user-visible text. <20 chars after this strip = the page renders no
+  // meaningful content server-side.
+  const stripped = bodyStr
+    .replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, "")
+    .replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, "")
+    .replace(/<noscript\b[^>]*>[\s\S]*?<\/noscript>/gi, "")
+    .replace(/<!--[\s\S]*?-->/g, "")
+    .replace(/<[^>]+>/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+
+  const hasRootDiv =
+    /<div\s+id=["']root["']\s*>\s*<\/div>/i.test(bodyStr) ||
+    /<div\s+id=["']app["']\s*>\s*<\/div>/i.test(bodyStr) ||
+    /<div\s+id=["']__next["']\s*>\s*<\/div>/i.test(bodyStr);
+
+  // <body> contains only <script>/<link>/<meta> + whitespace + comments.
+  // Common pattern for Vite/CRA shells without a labelled root div.
+  const bodyMatch = bodyStr.match(/<body\b[^>]*>([\s\S]*?)<\/body>/i);
+  let bodyOnlyScripts = false;
+  if (bodyMatch) {
+    const inner = bodyMatch[1].replace(/<!--[\s\S]*?-->/g, "");
+    const tagless = inner
+      .replace(/<(script|link|meta)\b[^>]*>[\s\S]*?<\/\1>/gi, "")
+      .replace(/<(script|link|meta)\b[^>]*\/?>/gi, "")
+      .trim();
+    bodyOnlyScripts = tagless.length === 0 && /<script\b/i.test(inner);
+  }
+
+  return { textBytes: stripped.length, hasRootDiv, bodyOnlyScripts };
+}
+
+function classifyFetchError(err) {
+  const name = err && err.name ? err.name : "";
+  const code = err && err.cause && err.cause.code ? err.cause.code : err && err.code ? err.code : "";
+  if (name === "AbortError" || name === "TimeoutError") return "timeout";
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") return "dns-fail";
+  if (code === "ECONNREFUSED" || code === "ECONNRESET" || code === "EHOSTUNREACH") return "tcp-fail";
+  if (code === "CERT_HAS_EXPIRED" || code === "DEPTH_ZERO_SELF_SIGNED_CERT") return "tls-fail";
+  return `fetch-err-${code || name || "unknown"}`;
+}
+
+async function main() {
+  let raw;
+  try {
+    raw = await readStdin();
+  } catch (err) {
+    emitVerdict([`verdict=inconclusive`, `reason=stdin-${err.message || "unknown"}`]);
+    return;
+  }
+
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    emitVerdict([`verdict=inconclusive`, `reason=stdin-not-json`]);
+    return;
+  }
+
+  const toolInput = payload && typeof payload === "object" ? payload.tool_input : null;
+  const url = toolInput && typeof toolInput.url === "string" ? toolInput.url : "";
+  if (!url) {
+    emitVerdict([`verdict=inconclusive`, `reason=no-url-in-tool-input`]);
+    return;
+  }
+
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    emitVerdict([`verdict=inconclusive`, `reason=unparseable-url`, `url=${JSON.stringify(url)}`]);
+    return;
+  }
+
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    emitVerdict([
+      `verdict=inconclusive`,
+      `reason=disallowed-scheme`,
+      `scheme=${parsed.protocol.replace(":", "")}`,
+    ]);
+    return;
+  }
+
+  // Cache key — strip fragment, normalise. Same URL across conversations
+  // hits the same cache entry; verdict is intrinsic to the response shape.
+  parsed.hash = "";
+  const cacheKey = parsed.toString();
+  const cacheHash = createHash("sha256").update(cacheKey).digest("hex").slice(0, 32);
+  const cacheDir = accountDir ? resolve(accountDir, "cache", "webfetch-preflight") : null;
+  const cachePath = cacheDir ? resolve(cacheDir, `${cacheHash}.json`) : null;
+
+  if (cachePath) {
+    try {
+      const stat = statSync(cachePath);
+      const ageMs = Date.now() - stat.mtimeMs;
+      if (ageMs < CACHE_TTL_MS) {
+        const cached = JSON.parse(readFileSync(cachePath, "utf8"));
+        if (cached && typeof cached.verdict === "string") {
+          const ageSec = Math.round(ageMs / 1000);
+          const fields = [
+            `verdict=${cached.verdict}`,
+            `body_bytes=${cached.body_bytes ?? 0}`,
+            `text_bytes=${cached.text_bytes ?? 0}`,
+            `cache=hit`,
+            `cache_age_s=${ageSec}`,
+            `url=${JSON.stringify(cacheKey)}`,
+          ];
+          if (cached.reason) fields.push(`reason=${cached.reason}`);
+          if (cached.verdict === "spa-shell") {
+            emitVerdict(fields, "block");
+            const bytes = cached.body_bytes ?? 0;
+            process.stderr.write(buildShortCircuitMessage(cacheKey, bytes) + "\n");
+            process.exit(2);
+          }
+          emitVerdict(fields);
+          return;
+        }
+      }
+    } catch {
+      // Cache miss or unreadable — continue to live probe.
+    }
+  }
+
+  let res;
+  try {
+    res = await fetch(parsed.toString(), {
+      headers: { Accept: "text/html,application/xhtml+xml,*/*;q=0.5" },
+      signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+      redirect: "follow",
+    });
+  } catch (err) {
+    emitVerdict([
+      `verdict=inconclusive`,
+      `reason=${classifyFetchError(err)}`,
+      `url=${JSON.stringify(cacheKey)}`,
+    ]);
+    return;
+  }
+
+  if (res.status >= 500) {
+    emitVerdict([
+      `verdict=inconclusive`,
+      `reason=http-${res.status}`,
+      `url=${JSON.stringify(cacheKey)}`,
+    ]);
+    return;
+  }
+
+  const contentType = (res.headers.get("content-type") || "").toLowerCase();
+  if (contentType && !contentType.includes("text/html") && !contentType.includes("application/xhtml")) {
+    emitVerdict([
+      `verdict=inconclusive`,
+      `reason=non-html-content-type`,
+      `ct=${JSON.stringify(contentType.slice(0, 60))}`,
+      `url=${JSON.stringify(cacheKey)}`,
+    ]);
+    return;
+  }
+
+  let body;
+  try {
+    body = await readBodyCapped(res, MAX_BODY_BYTES);
+  } catch (err) {
+    emitVerdict([
+      `verdict=inconclusive`,
+      `reason=body-read-${classifyFetchError(err)}`,
+      `url=${JSON.stringify(cacheKey)}`,
+    ]);
+    return;
+  }
+
+  const bodyBytes = body.length;
+  const bodyStr = body.toString("utf8");
+  const { textBytes, hasRootDiv, bodyOnlyScripts } = detectShape(bodyStr);
+
+  const isShell =
+    bodyBytes <= SHELL_BYTE_THRESHOLD &&
+    textBytes < TEXT_BYTE_THRESHOLD &&
+    (hasRootDiv || bodyOnlyScripts);
+
+  const verdict = isShell ? "spa-shell" : "ok";
+  const reason = isShell ? "js-spa-no-server-content" : undefined;
+
+  if (cachePath && cacheDir) {
+    try {
+      mkdirSync(cacheDir, { recursive: true });
+      writeFileSync(
+        cachePath,
+        JSON.stringify({
+          verdict,
+          body_bytes: bodyBytes,
+          text_bytes: textBytes,
+          reason,
+          url: cacheKey,
+          fetched_at: Date.now(),
+        }),
+      );
+    } catch {
+      // Best-effort. A failed cache write means the next probe re-runs;
+      // not a correctness issue.
+    }
+  }
+
+  const fields = [
+    `verdict=${verdict}`,
+    `body_bytes=${bodyBytes}`,
+    `text_bytes=${textBytes}`,
+    `cache=miss`,
+    `url=${JSON.stringify(cacheKey)}`,
+  ];
+  if (isShell) {
+    fields.push(`has_root_div=${hasRootDiv}`, `body_only_scripts=${bodyOnlyScripts}`, `reason=${reason}`);
+    emitVerdict(fields, "block");
+    process.stderr.write(buildShortCircuitMessage(cacheKey, bodyBytes) + "\n");
+    process.exit(2);
+  }
+  emitVerdict(fields);
+}
+
+function buildShortCircuitMessage(url, bodyBytes) {
+  // Wording is the actual content the LLM sees as tool_result. Names the
+  // failure class (machine-readable prefix), the reason in plain English,
+  // and the two concrete user actions that unblock the task. The directive
+  // not to silently retry is explicit because the model's instinct is to
+  // try Playwright next — that hides the failure from the user.
+  return (
+    `WEBFETCH_CANNOT_READ_JS_SPA: The HTML response at ${url} is a JavaScript ` +
+    `single-page-application shell (${bodyBytes} bytes, no server-rendered text). ` +
+    `WebFetch does not execute JavaScript, so it has no content to extract. ` +
+    `Do NOT retry WebFetch on this URL and do NOT silently dispatch another tool ` +
+    `(Playwright, research-assistant, memory-search) to substitute — that hides ` +
+    `the failure from the user. Stop, tell the user plainly that you cannot ` +
+    `read this URL because it renders content with JavaScript, and ask them to ` +
+    `paste the relevant text or send a screenshot.`
+  );
+}
+
+main().catch((err) => {
+  // Top-level safety net — fail-open. A crash in the preflight must never
+  // block a tool dispatch; the worst case is we lose the optimisation and
+  // pay the existing 60s timeout cost.
+  emitVerdict([`verdict=inconclusive`, `reason=preflight-crash`, `err=${JSON.stringify(String(err).slice(0, 80))}`]);
+});

package/payload/platform/plugins/admin/mcp/dist/__tests__/plugin-read-skill-resolution.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin-read-skill-resolution.test.d.ts.map

package/payload/platform/plugins/admin/mcp/dist/__tests__/plugin-read-skill-resolution.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-read-skill-resolution.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/plugin-read-skill-resolution.test.ts"],"names":[],"mappings":""}