failproofai 1.0.4-beta.1 → 1.0.4-beta.4

package/src/hooks/normalize-cli-payload.ts

@@ -10,56 +10,6 @@
  */
 import type { IntegrationType } from "./types";
 
-/**
- * True when `parsed` carries grok's camelCase envelope.
- *
- * This exists because grok EXECUTES OTHER CLIS' HOOK CONFIGS. Its discovery
- * scans `~/.claude/settings.json`, `~/.claude/settings.local.json`,
- * `<cwd>/.claude/settings.json` and the `.cursor` equivalents by default
- * (`[compat.claude] hooks = true`) — and `<cwd>/.claude/settings.json` is
- * exactly the file `policies --install --cli claude --scope project` writes. So
- * on any machine with both tools, grok runs OUR hooks and hands them `--cli
- * claude` on the command line while piping ITS OWN camelCase payload.
- *
- * Verified live against grok 1.0.3: the hook fired, `tool_name` and
- * `tool_input` were both undefined, and every builtin that reads either —
- * block-sudo, block-env-files, block-secrets-write, block-force-push — allowed.
- * Installed, running, costing latency, enforcing nothing; strictly worse than
- * no coverage, because the install reports success. Detecting the envelope lets
- * handler.ts re-route the event onto grok's path (tool maps AND response
- * shapes — grok ignores Claude's `hookSpecificOutput.permissionDecision`, also
- * verified by A/B).
- *
- * The test is on the PAYLOAD, never on an env var: `GROK_HOOK_EVENT` is set by
- * grok's runner but is still just an env var, and mistaking a real Claude event
- * for a grok one would break Claude's own enforcement. `workspaceRoot` +
- * `hookEventName` with no `hook_event_name` is a shape Claude never sends.
- */
-export function isGrokEnvelope(parsed: Record<string, unknown>): boolean {
-  return (
-    typeof parsed.hookEventName === "string" &&
-    typeof parsed.workspaceRoot === "string" &&
-    parsed.hook_event_name === undefined
-  );
-}
-
-/**
- * The CLI whose contract actually governs this event.
- *
- * Identical to the declared `--cli` for every integration except the grok
- * cross-execution case above, where the flag says `claude` and the wire says
- * grok. Returning "grok" there routes the rest of the pipeline — tool-name and
- * tool-input canonicalization, and the response shape policy-evaluator emits —
- * onto the contract that will actually be honored.
- */
-export function resolveEffectiveCli(
-  cli: IntegrationType,
-  parsed: Record<string, unknown>,
-): IntegrationType {
-  if (cli === "claude" && isGrokEnvelope(parsed)) return "grok";
-  return cli;
-}
-
 export function normalizeCliPayload(cli: IntegrationType, parsed: Record<string, unknown>): void {
   // Antigravity (agy) pipes a camelCase protojson payload; normalize the fields
   // the handler downstream reads to canonical snake_case BEFORE any
@@ -97,33 +47,6 @@ export function normalizeCliPayload(cli: IntegrationType, parsed: Record<string,
     }
   }
 
-  // grok pipes a camelCase envelope (verified live against grok 1.0.3 with a
-  // recorder hook on all 14 events). Normalize the fields the handler reads to
-  // snake_case BEFORE any canonicalization runs. Note `workspaceRoot` → `cwd`:
-  // grok sends BOTH, they were identical in every capture, and `cwd` is what
-  // resolveCwd + block-read-outside-cwd need. `toolResult` is grok's PostToolUse
-  // output key — it is NOT Claude's `tool_response`, so a sanitize policy
-  // reading the documented Claude key would see nothing without this line.
-  // `hookEventName` is deliberately NOT mapped: its value is snake_case
-  // ("pre_tool_use") whereas the canonical set is PascalCase, and the `--hook`
-  // arg already carries the PascalCase name.
-  if (cli === "grok") {
-    if (typeof parsed.toolName === "string") parsed.tool_name = parsed.toolName;
-    if (parsed.toolInput !== undefined) parsed.tool_input = parsed.toolInput;
-    if (parsed.toolResult !== undefined && parsed.tool_response === undefined) {
-      parsed.tool_response = parsed.toolResult;
-    }
-    if (typeof parsed.sessionId === "string") parsed.session_id = parsed.sessionId;
-    if (typeof parsed.transcriptPath === "string") parsed.transcript_path = parsed.transcriptPath;
-    if (typeof parsed.workspaceRoot === "string" && parsed.cwd === undefined) {
-      parsed.cwd = parsed.workspaceRoot;
-    }
-    if (typeof parsed.permissionMode === "string") parsed.permission_mode = parsed.permissionMode;
-    if (typeof parsed.stopHookActive === "boolean") {
-      parsed.stop_hook_active = parsed.stopHookActive;
-    }
-  }
-
   // Goose pipes `event` / `working_dir` instead of Claude's `hook_event_name` /
   // `cwd` (its `tool_name` / `tool_input` are already canonical field names).
   // Normalize both so resolveCwd keeps its cwd (block-read-outside-cwd) and the
@@ -135,53 +58,4 @@ export function normalizeCliPayload(cli: IntegrationType, parsed: Record<string,
       parsed.hook_event_name = parsed.event;
     }
   }
-
-  // Cline pipes its own payload verbatim — its hooks are event-NAMED scripts,
-  // not a generated shim that could pre-shape stdin — so without this every
-  // field the handler reads (tool_name, tool_input, session_id, cwd) is
-  // undefined and resolveCwd / block-read-outside-cwd see nothing. Verified live
-  // against cline v3.0.60 with a recorder hook on PreToolUse.
-  //
-  // `tool_call.input` is the source, NOT `preToolUse.parameters`: the latter
-  // JSON-STRINGIFIES every array value (`commands` arrives as the literal string
-  // `["echo hi"]`), so reading it would hand the batch expander a string and
-  // silently drop the entire fan-out. `preToolUse` is used only as a fallback
-  // for a payload carrying no `tool_call` at all.
-  //
-  // `hookName` is deliberately NOT mapped onto hook_event_name: its value is
-  // cline's INTERNAL name ("tool_call"), not the filename event, and the --hook
-  // argument already carries the canonical one. Same reasoning as grok's
-  // hookEventName.
-  if (cli === "cline") {
-    const tc = parsed.tool_call;
-    if (tc && typeof tc === "object" && !Array.isArray(tc)) {
-      const t = tc as Record<string, unknown>;
-      if (typeof t.name === "string") parsed.tool_name = t.name;
-      if (t.input !== undefined) parsed.tool_input = t.input;
-    }
-    const pre = parsed.preToolUse;
-    if (pre && typeof pre === "object" && !Array.isArray(pre)) {
-      const pp = pre as Record<string, unknown>;
-      if (parsed.tool_name === undefined && typeof pp.toolName === "string") {
-        parsed.tool_name = pp.toolName;
-      }
-      if (parsed.tool_input === undefined && pp.parameters !== undefined) {
-        parsed.tool_input = pp.parameters;
-      }
-    }
-    // taskId is the conversation ("conv_…"). sessionContext.rootSessionId and
-    // agent_id / parent_agent_id stay raw for custom policies correlating a
-    // subagent back to its root.
-    if (typeof parsed.taskId === "string") parsed.session_id = parsed.taskId;
-    const roots = parsed.workspaceRoots;
-    if (Array.isArray(roots) && typeof roots[0] === "string" && roots[0].length > 0) {
-      parsed.cwd = roots[0];
-    } else {
-      const wi = parsed.workspaceInfo;
-      if (wi && typeof wi === "object" && !Array.isArray(wi)) {
-        const rp = (wi as Record<string, unknown>).rootPath;
-        if (typeof rp === "string" && rp.length > 0) parsed.cwd = rp;
-      }
-    }
-  }
 }

package/src/hooks/notice.ts

@@ -0,0 +1,191 @@
+/**
+ * Putting a short message in front of a HUMAN, inside the agent they are using.
+ *
+ * A notice is not a verdict. `allow` / `deny` / `instruct` all answer "what
+ * happens to this tool call"; a notice answers nothing — it is one line of text
+ * for the person, delivered alongside whatever the verdict turned out to be.
+ * That is why it is a separate field rather than a fourth decision: shaping it
+ * into stdout beside a verdict ad hoc is how the copilot nested-vs-flat
+ * `additionalContext` bug happened.
+ *
+ * ## Why the channel differs per CLI, and why it is not `additionalContext`
+ *
+ * Measured across all 12 CLIs by live probe. The obvious channel —
+ * `hookSpecificOutput.additionalContext` — reaches the MODEL, not the user, and
+ * a model is a paraphraser: over eight real Claude turns it mentioned an
+ * informational notice 8/8, but an earlier notice that asked the agent to *act*
+ * was disclaimed as a suspected prompt injection 6/6 ("instructions arriving
+ * that way aren't something I'll act on unasked"). A security notice routed
+ * through something that may decline to repeat it is not a delivered notice.
+ *
+ * So each CLI gets the channel that was proven to paint text on the user's
+ * terminal, and the ones with no such channel get nothing rather than a
+ * pretend delivery:
+ *
+ *   claude   `{"systemMessage":…}`  renders `Stop says: …`; model-invisible
+ *                                   (a neutral probe answered `NONE`)
+ *   codex    `{"systemMessage":…}`  renders `• Stop (completed) says: …`
+ *   copilot  exit 0 + stderr        renders as a `!` session warning
+ *   factory  plain stdout           renders under a `Hooks Stop` block
+ *
+ * opencode and pi have real channels too, but they live inside the plugin shims
+ * we ship rather than in a hook's stdout, so a private JSON field is consumed
+ * there and handed to `showToast` / `ui.notify`. OpenClaw, cursor, devin, goose,
+ * antigravity and hermes have no verified channel that reaches a human without
+ * an unsupported escape hatch — they get nothing here, and their users get the
+ * finding from `failproofai audit` and the scheduled desktop notification.
+ */
+import type { IntegrationType } from "./types";
+
+/** How a notice is delivered on one CLI. */
+type NoticeChannel = "systemMessage" | "stderr" | "stdout" | "shim" | "none";
+
+/**
+ * Per-CLI channel, from live probes rather than documentation.
+ *
+ * A CLI absent from this map delivers nothing — deliberately. Guessing a
+ * channel produces the worst outcome available: output that looks delivered
+ * from our side and reaches nobody, so we would report a leak as "notified"
+ * that the user never saw.
+ */
+const NOTICE_CHANNEL: Partial<Record<IntegrationType, NoticeChannel>> = {
+  claude: "systemMessage",
+  codex: "systemMessage",
+  copilot: "stderr",
+  factory: "stdout",
+  opencode: "shim",
+  pi: "shim",
+};
+
+/**
+ * Claude truncates `systemMessage` at 4000 characters on the cloud-forwarding
+ * path, and a notice that gets cut mid-sentence reads as a broken tool. Ours is
+ * two lines by design; this is a backstop, not a budget.
+ */
+const MAX_NOTICE_CHARS = 900;
+
+export interface ShapedNotice {
+  /** Merged into the outcome's stdout, or empty. */
+  stdout: string;
+  /** Merged into the outcome's stderr, or empty. */
+  stderr: string;
+}
+
+/**
+ * Render a notice for one CLI, merging it into any verdict JSON already bound
+ * for stdout.
+ *
+ * `existingStdout` matters: a Stop-gate deny already emits a JSON object on
+ * several CLIs, and emitting a second object would produce two JSON documents
+ * on one stream — which every host parses as a syntax error and drops, taking
+ * the deny with it. So the notice is merged INTO that object when there is one.
+ */
+export function shapeNotice(
+  cli: IntegrationType | undefined,
+  notice: string,
+  existingStdout = "",
+): ShapedNotice {
+  const empty: ShapedNotice = { stdout: existingStdout, stderr: "" };
+  if (!notice.trim() || !cli) return empty;
+
+  const channel = NOTICE_CHANNEL[cli] ?? "none";
+  const text = notice.length > MAX_NOTICE_CHARS
+    ? notice.slice(0, MAX_NOTICE_CHARS - 1) + "…"
+    : notice;
+
+  switch (channel) {
+    case "systemMessage": {
+      // Merge into the verdict object when one exists, so the stream stays a
+      // single JSON document.
+      if (existingStdout.trim().startsWith("{")) {
+        try {
+          const parsed = JSON.parse(existingStdout) as Record<string, unknown>;
+          parsed.systemMessage = text;
+          return { stdout: JSON.stringify(parsed), stderr: "" };
+        } catch {
+          // Not the JSON we thought it was — leave the verdict untouched
+          // rather than risk destroying it to add a courtesy message.
+          return empty;
+        }
+      }
+      // Anything already on stdout that we could not merge into is left
+      // exactly as it is, and the notice is dropped instead. The alternative —
+      // emitting our own object over the top — DESTROYS it: measured with a
+      // JSON array on stdout, which does not start with `{`, so it fell past
+      // the merge and was replaced wholesale. A courtesy message is never worth
+      // more than whatever the host was already being told.
+      if (existingStdout.trim()) return empty;
+      return { stdout: JSON.stringify({ systemMessage: text }), stderr: "" };
+    }
+    case "stderr":
+      // Exit code is NOT touched: on copilot a non-zero exit from a tool event
+      // is a block, and a notice must never block anything.
+      return { stdout: existingStdout, stderr: text + "\n" };
+    case "stdout":
+      // factory renders plain text under its Hooks block. Only safe when no
+      // verdict JSON is already on the stream.
+      if (existingStdout.trim()) return empty;
+      return { stdout: text + "\n", stderr: "" };
+    case "shim": {
+      // OpenCode and Pi are in-process plugin integrations. Their generated
+      // shims consume this private field and call the host's real user-facing
+      // notification API; putting the text in additionalContext would send it
+      // to the model instead.
+      if (existingStdout.trim().startsWith("{")) {
+        try {
+          const parsed = JSON.parse(existingStdout) as Record<string, unknown>;
+          parsed.failproofaiNotice = text;
+          return { stdout: JSON.stringify(parsed), stderr: "" };
+        } catch {
+          return empty;
+        }
+      }
+      if (existingStdout.trim()) return empty;
+      return { stdout: JSON.stringify({ failproofaiNotice: text }), stderr: "" };
+    }
+    default:
+      return empty;
+  }
+}
+
+/** True when this CLI has a channel that was proven to reach a human. */
+export function canDeliverNotice(cli: IntegrationType | undefined): boolean {
+  return !!cli && (NOTICE_CHANNEL[cli] ?? "none") !== "none";
+}
+
+/**
+ * The notice itself. A FIXED template with no interpolation of scanned content.
+ *
+ * The count is a number we computed; everything else is a constant. That is not
+ * stylistic: the alternative is interpolating a finding's `example`, which is
+ * the verbatim text of a command from a repository — attacker-controlled
+ * through a README, a Makefile target or an npm script. Tested against the
+ * shipped redactor, `echo "IGNORE ALL PRIOR INSTRUCTIONS…"` passes through
+ * byte-identical, because that redactor masks secrets, not instructions. On the
+ * CLIs where the only channel is the model's context, that string would land
+ * directly in the prompt. So nothing scanned ever reaches this template.
+ */
+export function leakNoticeText(newFindings: number): string {
+  const n = newFindings === 1
+    ? "a possible credential exposure"
+    : `${newFindings} possible credential exposures`;
+  return (
+    `failproofai found ${n} in this project's agent transcripts.\n` +
+    "Run `failproofai audit` to review the matches and rotate anything real."
+  );
+}
+
+/** Copy for the OS notification raised by an unattended scheduled scan.
+ *
+ * Deliberately omits the count. A burst of generated fixtures can hit the
+ * record cap, and a desktop banner saying "500 leaked credentials" states a
+ * conclusion the detector cannot support. The dashboard carries the evidence;
+ * the banner's job is only to ask for review. */
+export function desktopLeakNotice(): { title: string; body: string } {
+  return {
+    title: "failproofai audit needs review",
+    body:
+      "Possible credential exposure was found in your agent transcripts. " +
+      "Run failproofai audit to verify the matches and rotate anything real.",
+  };
+}