failproofai 1.0.7-beta.2 → 1.0.8-beta.0

package/src/hooks/policy-authority.ts

@@ -91,7 +91,7 @@ export const SEMANTIC_POLICY_NAMES = [
  * A pack that declares its own `semantic` entries replaces
  * `SEMANTIC_POLICIES` wholesale on the machine that installed it, so the names
  * a `reviewedBy` may use there are the pack's. Callers that know which set is
- * live pass it (`effectiveReviewerNames()` in `pack-manifest.ts`, which reads
+ * live pass it (`effectiveReviewerNames()` in `effective-reviewers.ts`, which reads
  * the manifest and imports nothing from `semantic/`); everyone else gets this
  * one, which is what a machine with no pack runs.
  */
@@ -124,6 +124,8 @@ const isName = (n: unknown): n is string => typeof n === "string" && n.length >
 export function resolvePolicyAuthority(
   decl: AuthorityDeclaration | undefined,
   knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
+  /** Names left out of `knownReviewers` because packs declare them differently, with those packs. */
+  contested?: ReadonlyMap<string, string[]>,
 ): ResolvedAuthority {
   const declaredReviewable = decl?.authority === "reviewable";
   if (!decl || effectiveAuthority(decl) === "hard") {
@@ -136,16 +138,28 @@ export function resolvePolicyAuthority(
   }
   const unknown = names.filter((n) => !knownReviewers.has(n));
   if (unknown.length > 0) {
-    return {
-      authority: "hard",
-      downgraded:
-        `reviewedBy names ${unknown.map((n) => JSON.stringify(n)).join(", ")}, ` +
-        `which ${unknown.length === 1 ? "is not a semantic policy" : "are not semantic policies"} in this build`,
-    };
+    return { authority: "hard", downgraded: `reviewedBy names ${unknown.map((n) => whyUnknown(n, knownReviewers, contested)).join("; ")}` };
   }
   return { authority: "reviewable", reviewedBy: [...new Set(names)] };
 }
 
+/**
+ * The rule that kept one name out. "Not in this build" is only true of the
+ * compiled-in set: a pack's own checks, or a name two packs disagree on, is a
+ * different reason, and the author reading it has a different fix.
+ */
+function whyUnknown(name: string, known: ReadonlySet<string>, contested?: ReadonlyMap<string, string[]>): string {
+  // Quoted with JSON.stringify: a pack's name reaches the hook's stderr, so a
+  // control character in it must not reach the terminal raw.
+  const quoted = JSON.stringify(name);
+  const claimants = contested?.get(name);
+  if (claimants) return `${quoted}, which packs ${claimants.join(" and ")} declare differently, so it is asked for neither`;
+  if (known === SEMANTIC_REVIEWER_NAMES) return `${quoted}, which is not a semantic policy in this build`;
+  const sorted = [...known].sort();
+  const listed = sorted.length > 6 ? `${sorted.slice(0, 6).join(", ")} and ${sorted.length - 6} more` : sorted.join(", ");
+  return `${quoted}, which is not among the Jev checks it is judged against (${listed})`;
+}
+
 function whyHard(decl: AuthorityDeclaration): string {
   if (decl.alwaysOn === true) return "it is alwaysOn, and the self-protection guard is never reviewable";
   if (!Array.isArray(decl.reviewedBy) || decl.reviewedBy.length === 0) {
@@ -238,37 +252,76 @@ export function manifestAuthority(
  * So it resolves toward HARD, the way the collapse resolves the effect toward
  * enforce: reviewable only when EVERY declaration resolves to reviewable, and
  * then through the UNION of their checks (more checks that must all come back
- * clear is stricter, never weaker). Otherwise it takes the first declaration
- * that is not reviewable, so a refused one is still reported at registration.
+ * clear is stricter, never weaker).
+ *
+ * ## What the merged record may carry, and why it is the RESOLUTION
+ *
+ * Nothing here copies a declaration through. It used to keep the first one that
+ * was not reviewable, so that a refused `reviewable` would be reported again at
+ * registration — and that was the hole: a declaration is only ever resolved
+ * against the reviewer set of whoever is looking, so a `reviewable` naming a
+ * PACK's own check resolved to hard here, against the builtin set, and was
+ * copied forward verbatim. `registerPolicy` then resolved that same raw
+ * declaration against `effectiveReviewerNames()`, which does have the pack's
+ * check — and the policy registered reviewable, with a hard peer behind the same
+ * artifact overruled by nothing more than which pack was listed first.
+ *
+ * Two changes close it. The reviewer set is now a PARAMETER, so the merge judges
+ * by the same names registration will; and a non-reviewable merge emits
+ * `{ authority: "hard" }` — the resolved value — rather than the fields it was
+ * asked for. Either alone would have been enough for the case above; both,
+ * because the first is an agreement between two callers and the second holds
+ * whether or not they agree.
+ *
+ * The reason a refused declaration carried is not lost: it comes back as
+ * `refused`, for the caller to say through {@link refusedAuthorityWarning} at
+ * the point where it knows which artifact and which packs are involved.
  *
  * Returns `record` itself when its own fields already say that, and a copy with
  * only the two authority fields replaced otherwise. `overruled` is true when
  * some declaration asked for reviewable, validly, and did not get it.
+ *
+ * @param knownReviewers - the checks that can be asked on this machine. Callers
+ *   that merge what will be REGISTERED must pass `effectiveReviewerNames()`;
+ *   the default is this build's compiled-in set, which is what a machine with no
+ *   pack runs.
  */
 export function withMergedAuthority<T extends AuthorityFields>(
   record: T,
   declarations: ReadonlyArray<AuthorityFields>,
-): { merged: T; overruled: boolean } {
-  const resolved = declarations.map((d) => resolvePolicyAuthority(d));
+  knownReviewers: ReadonlySet<string> = SEMANTIC_REVIEWER_NAMES,
+): { merged: T; overruled: boolean; refused?: string } {
+  const resolved = declarations.map((d) => resolvePolicyAuthority(d, knownReviewers));
   const allReviewable = resolved.length > 0 && resolved.every((r) => r.authority === "reviewable");
+  // The declaration that decided it is hard. Its own fields are not carried —
+  // only whether it said anything at all, because a record that declared
+  // nothing is already hard and rewriting it to say so would touch a record the
+  // collapse has no business touching.
+  const decided = declarations[resolved.findIndex((r) => r.authority !== "reviewable")] ?? {};
   const fields: AuthorityFields = allReviewable
     ? { authority: "reviewable", reviewedBy: [...new Set(resolved.flatMap((r) => r.reviewedBy ?? []))] }
-    : fieldsOf(declarations[resolved.findIndex((r) => r.authority !== "reviewable")] ?? {});
+    : decided.authority === undefined
+      ? {}
+      : { authority: "hard" };
   const overruled = !allReviewable && resolved.some((r) => r.authority === "reviewable");
+  const refused = resolved.find((r) => r.downgraded !== undefined)?.downgraded;
+  const extra = refused === undefined ? {} : { refused };
   const same =
     record.authority === fields.authority &&
     JSON.stringify(record.reviewedBy) === JSON.stringify(fields.reviewedBy);
-  if (same) return { merged: record, overruled };
+  if (same) return { merged: record, overruled, ...extra };
   const { authority: _a, reviewedBy: _r, ...rest } = record;
-  return { merged: { ...rest, ...fields } as T, overruled };
+  return { merged: { ...rest, ...fields } as T, overruled, ...extra };
 }
 
-/** The authority fields a record actually carries, and nothing else. */
-function fieldsOf(d: AuthorityFields): AuthorityFields {
-  return {
-    ...(d.authority !== undefined ? { authority: d.authority } : {}),
-    ...(d.reviewedBy !== undefined ? { reviewedBy: d.reviewedBy } : {}),
-  };
+/**
+ * The warning for a `reviewable` declaration that was not honored. One
+ * phrasing, wherever it is noticed — registration for a policy that reaches it
+ * with its declaration intact, and the loader for one the collapse hardened
+ * before it got there.
+ */
+export function refusedAuthorityWarning(subject: string, reason: string): string {
+  return `${subject} asks to be reviewable, but ${reason} — it stays hard`;
 }
 
 const warnedAuthority = new Set<string>();

package/src/hooks/policy-catalog.ts

@@ -457,13 +457,14 @@ export const POLICY_CATALOG: PolicyCatalogEntry[] = [
     // policy off on every machine that configured Jev, while the mark said
     // otherwise.
     //
-    // The test that matters is not "can the reviewer keep this block" but "is
-    // there anything left that can deny". `block-read-outside-cwd` also has only
-    // an instruct reviewer and stays reviewable, because when it clears,
-    // `secret-exposure` and `credential-exfiltration` are still asked about the
-    // same read and still deny on their own through the most-severe merge. Here
-    // nothing else covers committing on a protected branch, so a clear leaves
-    // the concern unenforced by anything.
+    // The engine has since changed under that argument: a reviewer that FIRES
+    // with nobody consenting now keeps the block (`combine.ts`, "A check that
+    // fired without consent keeps the floor"), so an instruct-only reviewer is
+    // no longer "off". `block-read-outside-cwd`, which also has only an
+    // instruct reviewer, stays reviewable on exactly that rule: it clears when
+    // the read is requested or the check finds nothing, and keeps the deny on
+    // an unrequested read it flags. Making this one reviewable again is a
+    // product call nobody has made.
     authority: "hard",
     defaultEnabled: false,
     category: "Git",
@@ -526,7 +527,8 @@ export const POLICY_CATALOG: PolicyCatalogEntry[] = [
     // question as written.
     //
     // A named check that is asked and does not fire answers "no concern", and
-    // that CLEARS (`combine.ts`, "A warning-level answer clears the deny"). So
+    // that CLEARS (`combine.ts`, "A check that fired without consent keeps the
+    // floor"). So
     // pairing this policy with `destructive-deletion` would not hand the
     // decision to Jev — it would switch the policy off on every machine that
     // configured Jev, which is exactly the `block-work-on-main` mistake. The

package/src/hooks/policy-evaluator.ts

@@ -17,7 +17,16 @@ export { packPolicyParamKey } from "./pack-param-key";
 import { DEFAULT_POLICY_NAMESPACE, getPoliciesForEvent } from "./policy-registry";
 // Type-only apart from the two pure functions: the semantic evaluator itself is
 // loaded by handler.ts, lazily, and only when a Jev config exists.
-import { combineTwoTier, regexOnly, type FinalVerdict, type JevActivityFields, type JevReview, type RegexVerdict, type TwoTierReview } from "./semantic/combine";
+import {
+  combineTwoTier,
+  regexOnly,
+  type FinalVerdict,
+  type JevActivityFields,
+  type JevReview,
+  type RegexVerdict,
+  type ShadowVerdict,
+  type TwoTierReview,
+} from "./semantic/combine";
 // The code, not a copy of the string: the log line below turns on it, and a
 // rename should break the build here rather than quietly print "unavailable"
 // for a call Jev actually answered.
@@ -51,6 +60,10 @@ export interface EvaluationResult {
     activity: JevActivityFields;
     /** True when Jev's own verdict is what `policyName` names. */
     decidedByJev: boolean;
+    /** The pack a deciding Jev check came from; only with `decidedByJev`. */
+    jevOrigin?: { packId: string; packVersion?: string };
+    /** Shadow mode: Jev's own deny/instruct, recorded as a "would have" (see `ShadowVerdict`). */
+    shadowVerdict?: ShadowVerdict;
   };
 }
 
@@ -233,8 +246,13 @@ export async function evaluatePolicies(
     );
   }
   return {
-    ...formatVerdict(eventType, session, toolName, combined.final),
-    twoTier: { activity: combined.activity, decidedByJev: combined.decidedByJev },
+    ...formatVerdict(eventType, session, toolName, combined.final, combined.decidedByJev),
+    twoTier: {
+      activity: combined.activity,
+      decidedByJev: combined.decidedByJev,
+      ...(combined.decidedByJev && review.kind === "answered" && review.origin ? { jevOrigin: review.origin } : {}),
+      ...(combined.shadowVerdict ? { shadowVerdict: combined.shadowVerdict } : {}),
+    },
   };
 }
 
@@ -350,16 +368,17 @@ async function collectVerdicts(
   return { verdicts, hardDenied: false };
 }
 
-/** A verdict → the calling CLI's response. Which engine decided is irrelevant here. */
+/** A verdict → the calling CLI's response. Which engine decided only changes whom a deny credits. */
 function formatVerdict(
   eventType: HookEventType,
   session: SessionMetadata | undefined,
   toolName: string | undefined,
   final: FinalVerdict,
+  byJev = false,
 ): EvaluationResult {
   if (final.decision === "deny") {
     const [decider] = final.entries;
-    return formatDeny(eventType, session, toolName, decider.policyName, decider.reason);
+    return formatDeny(eventType, session, toolName, decider.policyName, decider.reason, byJev);
   }
   if (final.decision === "instruct") return formatInstruct(eventType, session, final.entries);
   if (final.entries.length > 0) return formatAllow(eventType, session, final.entries);
@@ -372,6 +391,7 @@ function formatDeny(
   toolName: string | undefined,
   policyName: string,
   reason: string,
+  byJev = false,
 ): EvaluationResult {
   // Pick a noun for the deny message that fits the event type. Tool events
   // get the tool name; non-tool events (UserPromptSubmit, SessionStart,
@@ -391,7 +411,10 @@ function formatDeny(
   } else {
     displayTool = "operation";
   }
-  const blockedMessage = `Blocked ${displayTool} by failproofai because: ${reason}, as per the policy configured by the user`;
+  // Jev's reason is its own sentences, ending in "."; no user configured the check.
+  const blockedMessage = byJev
+    ? `Blocked ${displayTool} by failproofai because: ${reason.replace(/[.\s]+$/, "")}, as flagged by Jev semantic review`
+    : `Blocked ${displayTool} by failproofai because: ${reason}, as per the policy configured by the user`;
 
   // Cursor's hook protocol expects a flat `{permission, user_message,
   // agent_message}` shape for any blocking decision, regardless of which
@@ -722,7 +745,7 @@ function formatDeny(
         hookEventName: eventType,
         decision: {
           behavior: "deny",
-          message: `Blocked ${displayTool} by failproofai because: ${reason}, as per the policy configured by the user`,
+          message: blockedMessage,
         },
       },
     };
@@ -777,7 +800,7 @@ function formatDeny(
     const response = {
       hookSpecificOutput: {
         hookEventName: eventType,
-        additionalContext: `Blocked ${displayTool} by failproofai because: ${reason}, as per the policy configured by the user`,
+        additionalContext: blockedMessage,
       },
     };
     return {

package/src/hooks/policy-registry.ts

@@ -127,14 +127,15 @@ export function getPoliciesForEvent(
   return result;
 }
 
-export function clearPolicies(): void {
+/** `cli`: the agent this pass registers for, which scopes the Jev reviewer set. */
+export function clearPolicies(cli?: string): void {
   const g = globalThis as GlobalWithRegistry;
   g[REGISTRY_KEY] = [];
   setIndexCache(null);
   // The reviewer set describes the policies that are about to be registered, so
   // it is rebuilt with them. Dropping it here is also what keeps one read per
   // evaluation instead of one per policy.
-  forgetEffectiveReviewerNames();
+  forgetEffectiveReviewerNames(cli);
 }
 
 /**

package/src/hooks/policy-reviewability.ts

@@ -49,18 +49,26 @@
  * - **Policies from the user's own files.** A custom hook declares its
  *   authority inside the module, so counting one means importing and running
  *   somebody's JavaScript — from a settings page, on every read. The count of
- *   configured custom policy PATHS is reported instead, and the summary says
- *   in words that those policies were not counted.
+ *   custom policy FILES the hook loads (configured paths and the project and
+ *   user convention files) is reported instead, the summary says in words that
+ *   those policies were not counted, and no "never" is diagnosed beside them.
  * - **A session pause.** It suspends local policy for minutes, and a warning
  *   about a policy set that is coming back shortly would be noise.
  */
 import { readActiveCloudManagedPolicies } from "./cloud-managed-policies";
-import { configuredCustomPolicyPaths, readMergedHooksConfig } from "./hooks-config";
-import { hasInstalledPacks, packSemantic, readInstalledPacks } from "./pack-manifest";
-import { resolvePolicyAuthority } from "./policy-authority";
+import { jevPacks } from "./effective-reviewers";
+import { resolve } from "node:path";
+import { discoverPolicyFiles } from "./custom-hooks-loader";
+import { customPoliciesDir } from "./fp-home";
+import { configuredCustomPolicyPaths, findProjectConfigDir, readMergedHooksConfig } from "./hooks-config";
+import { hasInstalledPacks, readInstalledPacks } from "./pack-manifest";
+import { resolvePolicyAuthority, SEMANTIC_REVIEWER_NAMES } from "./policy-authority";
 import { POLICY_CATALOG } from "./policy-catalog";
 import { normalizePolicyName } from "./policy-registry";
 import type { HooksConfig } from "./policy-types";
+// A CLI and dashboard module, never on the hook path, so it may ask the
+// resolver itself (`pack-cli.ts` does the same).
+import { semanticPoliciesFromPacks } from "./semantic/pack-policies";
 
 /** Anything that carries an authority declaration: a catalog entry, a pack entry, a cloud record. */
 export interface AuthorityRecord {
@@ -74,7 +82,10 @@ export interface ReviewableCoverage {
   enabled: number;
   /** Of those, the ones Jev may clear a deny or an instruct from. */
   reviewable: number;
-  /** Configured custom policy paths, whose policies are not in the counts above. */
+  /**
+   * Custom policy files the hook loads — configured paths and the project and
+   * user convention files — whose policies are not in the counts above.
+   */
   customFiles: number;
 }
 
@@ -144,14 +155,21 @@ export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
    * A pack's `enabled` selection is deliberately not applied: it narrows which
    * of its REGEX policies register, and its semantic set is not selectable.
    */
-  const packReviewers = new Set<string>();
+  let reviewers: ReadonlySet<string> | undefined;
   try {
     packsInstalled = hasInstalledPacks();
-    for (const pack of readInstalledPacks().packs) {
+    const packs = readInstalledPacks().packs;
+    for (const pack of packs) {
       const selected = pack.enabled;
       records.push(...(selected ? pack.policies.filter((p) => selected.includes(p.name)) : pack.policies));
-      for (const entry of packSemantic(pack)) packReviewers.add(entry.name);
     }
+    // The names of the questions a request will actually carry: only the packs
+    // whose checks take part (an observe pack's do not), minus a reserved or
+    // contested name AND minus a check the question budget drops — which the
+    // hook path's manifest-only `reviewerNamesFor` cannot see. Anything else and
+    // the panel and `jev status` promise a clear that cannot happen.
+    const asked = semanticPoliciesFromPacks(jevPacks(packs));
+    reviewers = asked.fromPack ? new Set(asked.policies.map((p) => p.name)) : SEMANTIC_REVIEWER_NAMES;
   } catch {
     // An unreadable manifest enforces nothing; `readInstalledPacks` already
     // reports that to the hook log on the path that cares.
@@ -178,14 +196,23 @@ export function surveyReviewableCoverage(cwd?: string): ReviewableCoverage {
     // Same fail-open as the handler's own read of this file.
   }
 
+  // Every file `loadAllCustomHooks` would load, by resolved path so a file
+  // both named and discovered (or a project root that IS home) counts once.
   let customFiles = 0;
   try {
-    customFiles = configuredCustomPolicyPaths(config).length;
+    // Relative paths against the project root, as the loader resolves them.
+    const projectRoot = findProjectConfigDir(cwd ?? process.cwd());
+    const files = new Set(configuredCustomPolicyPaths(config).map((p) => resolve(projectRoot, p)));
+    if (config.customPoliciesEnabled !== false) {
+      const projectDir = resolve(projectRoot, ".failproofai", "policies");
+      for (const dir of [projectDir, customPoliciesDir()]) for (const f of discoverPolicyFiles(dir)) files.add(f);
+    }
+    customFiles = files.size;
   } catch {
     customFiles = 0;
   }
 
-  return { ...countReviewable(records, packReviewers.size > 0 ? packReviewers : undefined), customFiles };
+  return { ...countReviewable(records, reviewers), customFiles };
 }
 
 /**
@@ -219,7 +246,9 @@ export function reviewableSummary(coverage: ReviewableCoverage): string {
  * did not ask.
  */
 export function reviewableProblem(coverage: ReviewableCoverage): string | null {
-  if (coverage.enabled === 0 || coverage.reviewable > 0) return null;
+  // Policies from the user's own files were not counted and may be reviewable,
+  // so "never" cannot be said honestly; the summary already says what was skipped.
+  if (coverage.enabled === 0 || coverage.reviewable > 0 || coverage.customFiles > 0) return null;
   return (
     "Jev can add a deny or an instruction on this machine, but it can never clear one. " +
     "No enabled policy is marked reviewable — a policy pack published before this release carries no such marks — " +

package/src/hooks/policy-types.ts

@@ -47,7 +47,8 @@ export interface RegisteredPolicy {
   authority?: PolicyAuthority;
   /**
    * The semantic policies (`src/hooks/semantic/policies.ts`) that must all be
-   * asked, and none of which may answer `deny`, before Jev clears this policy.
+   * asked, and each clear (see {@link PolicyAuthority}), before Jev clears this
+   * policy.
    */
   reviewedBy?: string[];
 }
@@ -58,8 +59,9 @@ export interface RegisteredPolicy {
  * - `hard`: final. Jev can never clear it.
  * - `reviewable`: Jev may clear it, but only through the semantic policies
  *   named in `reviewedBy`, and only when every one of them was actually asked
- *   and none of them answered `deny` — a `none`, `overridden` or `instruct`
- *   answer clears it (`combine.ts`, "A warning-level answer clears the deny").
+ *   and each answered `none`, `overridden`, or a deny the human's task
+ *   softened to a warning (`combine.ts`, "A check that fired without consent
+ *   keeps the floor").
  *   A named check that was NOT asked always keeps the verdict standing.
  */
 export type PolicyAuthority = "hard" | "reviewable";