@remembrance-ai/opencode-plugin 0.1.60 → 0.1.63

package/README.md

@@ -57,12 +57,26 @@ An optional single-use token from **Dashboard > Agents > Instances > Install on
 this device** links the installation to the signed-in member so bounded working
 preferences can follow that engineer. The token expires after ten
 minutes and never belongs in reusable key-distribution instructions. Unlinked
-installs remain fully functional with installation-local preferences. Built-in
-controls cover common presentation choices; extensible preferences can guide
-discretionary workflow and strategy selection. They may reorder only
-already-relevant skills inside one match tier or apply a surgical sidecar, and
-can never weaken safety, authorization, privacy, applicability, required skill
-steps, validation, review, or organization policy.
+installs remain fully functional with installation-local preferences. Private
+working preferences follow each engineer across approved agents and steer
+relevant public and team skills without changing shared instructions or
+weakening organization policy. Profiles, observations, compatibility records,
+and feedback remain private to the organization. Classification runs
+asynchronously against exact skill versions; query and invocation add no
+generative preference call or second embedding request. Material compatibility
+may reorder only already-relevant skills inside one match tier or apply a
+surgical sidecar. Missing or stale coverage is neutral, and no preference can
+weaken safety, authorization, privacy, applicability, required skill steps,
+validation, review, or organization policy. Exact skill-version changes queue
+only that skill for affected organizations; blocked classification resumes
+automatically when the organization becomes eligible.
+
+After actually using an exact skill version, the agent may call
+`submit_preference_compatibility_feedback` only with the exact correlation IDs
+and server-issued preference fingerprint in that result's feedback offer. The
+server verifies the fetch and active preference. The operation requires a
+verified principal session, remains private to the organization, and never
+edits the skill.
 
 ## Organization key
 

package/opencode.json

@@ -3,7 +3,11 @@
   "mcp": {
     "remembrance": {
       "type": "local",
-      "command": ["npx", "-y", "@remembrance-ai/mcp-server@0.1.60"],
+      "command": [
+        "npx",
+        "-y",
+        "@remembrance-ai/mcp-server@0.1.63"
+      ],
       "enabled": true,
       "environment": {
         "REMEMBRANCE_PLUGIN_HOST": "opencode",
@@ -11,5 +15,7 @@
       }
     }
   },
-  "plugin": ["@remembrance-ai/opencode-plugin@0.1.60"]
+  "plugin": [
+    "@remembrance-ai/opencode-plugin@0.1.63"
+  ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remembrance-ai/opencode-plugin",
-  "version": "0.1.60",
+  "version": "0.1.63",
   "license": "Apache-2.0",
   "description": "opencode plugin for Remembrance session hooks, tool observation, and contribution nudges.",
   "type": "module",

package/scripts/hook-core.mjs

@@ -58,6 +58,33 @@ const VALUE_EPISODE_MARKER_LIMIT = 20;
 const VALUE_EPISODE_MARKER_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const DIRECT_SELECTION_MARKER_LIMIT = 20;
 const DIRECT_SELECTION_MARKER_TTL_MS = 24 * 60 * 60 * 1000;
+const PREFERENCE_EVIDENCE_SKILL_LIMIT = 2;
+const PREFERENCE_EVIDENCE_SETTING_LIMIT = 4;
+const PREFERENCE_EVIDENCE_CONTEXT_CHARS = 760;
+const EFFECTIVE_PREFERENCE_SOURCES = new Set([
+  "mandatory_org",
+  "explicit_task",
+  "explicit_project",
+  "explicit_member_runtime",
+  "explicit_member",
+  "learned_member_runtime",
+  "learned_member",
+  "explicit_installation",
+  "learned_installation",
+  "recommended_org",
+  "skill_default",
+]);
+const PREFERENCE_EVIDENCE_SOURCES = new Set([
+  "mandatory_org",
+  "explicit_project",
+  "explicit_member_runtime",
+  "explicit_member",
+  "learned_member_runtime",
+  "learned_member",
+  "explicit_installation",
+  "learned_installation",
+  "recommended_org",
+]);
 const MAX_LOCAL_CONFIG_BYTES = 64 * 1024;
 const MAX_LOCAL_HEALTH_MARKER_BYTES = 16 * 1024;
 const MAX_LOCAL_PLUGIN_ALERT_BYTES = 16 * 1024;
@@ -338,14 +365,27 @@ export function buildQueryPayload(
     redacted.length <= MAX_SUMMARY_CHARS
       ? redacted
       : `${redacted.slice(0, MAX_SUMMARY_CHARS - 3).trim()}...`;
-  const projectKey = projectKeyForHook(env, projectPath);
+  const credential = resolveApiCredential(env);
+  const organizationCredentialAvailable =
+    Boolean(credential.apiKey) &&
+    !isUnusableConfigurationSource(credential.source);
+  const projectKey = organizationCredentialAvailable
+    ? projectKeyForHook(env, projectPath)
+    : null;
   const resolvedClientContext = clientContext
-    ? {
-        ...clientContext,
-        ...(clientContext.project_key || !projectKey
-          ? {}
-          : { project_key: projectKey }),
-      }
+    ? (() => {
+        const { project_key: requestedProjectKey, ...publicClientContext } =
+          clientContext;
+        const authorizedProjectKey = organizationCredentialAvailable
+          ? requestedProjectKey || projectKey
+          : null;
+        return {
+          ...publicClientContext,
+          ...(authorizedProjectKey
+            ? { project_key: authorizedProjectKey }
+            : {}),
+        };
+      })()
     : null;
   return {
     agent: {
@@ -834,7 +874,7 @@ export function formatContext(
   );
   if (effectivePreferences.length > 0) {
     lines.push(
-      `Apply these persisted working preferences silently: ${effectivePreferences.join("; ")}. A clear current-task preference overrides every non-mandatory entry; a Required organization setting remains authoritative. Use preferences only for discretionary presentation, workflow, or strategy choices among already-applicable options. Never weaken applicability, safety, authorization, privacy, required skill steps, validation, or review.`,
+      `Apply these persisted working preferences silently: ${effectivePreferences.join("; ")}. Do not ask the user to reconfirm them or mention routine preference application in the final response. A clear current-task preference overrides every non-mandatory entry; a Required organization setting remains authoritative. Use preferences only for discretionary presentation, workflow, or strategy choices among already-applicable options. Never weaken applicability, safety, authorization, privacy, required skill steps, validation, or review.`,
     );
   }
   const queryId = body?.query_feedback?.query_id ?? body?.query_id;
@@ -878,6 +918,12 @@ export function formatContext(
       `After using Remembrance: ${safeText(contributionDirective, MAX_DIRECTIVE_CHARS)}`,
     );
   }
+  const preferenceEvidence = preferenceCompatibilityEvidenceFromResponse(body);
+  if (preferenceEvidence.length > 0) {
+    tailLines.push(
+      preferenceCompatibilityEvidenceInstruction(preferenceEvidence),
+    );
+  }
   if (skills.length > 0 || resources.length > 0) {
     tailLines.push(
       "Delegating this task? Pass the selected slug, query_id, and result_id to the subagent; it should fetch that result or run its own full-context query before custom work.",
@@ -1072,6 +1118,162 @@ function sanitizePreferenceApplication(value, effectivePreferences) {
     : `skill preference defaults ${settings.join("; ")}`;
 }
 
+export function preferenceCompatibilityEvidenceFromResponse(response) {
+  const body = responseBodyFromToolResponse(response);
+  const candidates = [
+    ...(body?.selection_mode === "explicit" && body?.skill
+      ? [
+          {
+            ...body.skill,
+            result_id: body.result_id,
+            effective_preferences: body.effective_preferences,
+            preference_compatibility_feedback:
+              body.preference_compatibility_feedback,
+          },
+        ]
+      : []),
+    ...(Array.isArray(body?.skills) ? body.skills : []),
+  ];
+  const seen = new Set();
+  return candidates
+    .flatMap((candidate) => {
+      const slug = safePreferenceIdentifier(candidate?.slug, 120);
+      if (!slug || seen.has(slug)) return [];
+      const feedback = candidate?.preference_compatibility_feedback;
+      const queryId = safeCorrelationIdentifier(feedback?.query_id, 160);
+      const resultId = safeCorrelationIdentifier(feedback?.result_id, 160);
+      const skillVersionId = safeCorrelationIdentifier(
+        feedback?.skill_version_id,
+        160,
+      );
+      const preferences = sanitizePreferenceFeedbackSettings(
+        feedback?.preferences,
+      );
+      if (
+        feedback?.available !== true ||
+        !queryId ||
+        !resultId ||
+        !skillVersionId ||
+        preferences.length === 0
+      ) {
+        return [];
+      }
+      seen.add(slug);
+      return [
+        {
+          query_id: queryId,
+          result_id: resultId,
+          skill_slug: slug,
+          skill_version_id: skillVersionId,
+          preferences,
+        },
+      ];
+    })
+    .slice(0, PREFERENCE_EVIDENCE_SKILL_LIMIT);
+}
+
+function preferenceCompatibilityEvidenceInstruction(evidence) {
+  const payload = boundedPreferenceEvidencePayload(evidence);
+  if (!payload) return "";
+  return [
+    "Private preference evidence (silent, after actual use only): if the selected skill clearly supports or conflicts with one server-issued working preference below, call submit_preference_compatibility_feedback using its exact query_id, result_id, preference_fingerprint, skill slug, and version id.",
+    'Judge observed behavior independently: selection and an existing classifier label are not new evidence. Skip neutral or uncertain cases. Use evidence_source "explicit_user" only for the user\'s explicit assessment; otherwise use "agent_observed". Never send task content, and do not ask the user or mention routine telemetry.',
+    `Candidates: ${payload}`,
+  ].join(" ");
+}
+
+function boundedPreferenceEvidencePayload(evidence) {
+  const entries = [];
+  for (const candidate of evidence.slice(0, PREFERENCE_EVIDENCE_SKILL_LIMIT)) {
+    for (const preference of candidate.preferences.slice(
+      0,
+      PREFERENCE_EVIDENCE_SETTING_LIMIT,
+    )) {
+      const next = {
+        query_id: candidate.query_id,
+        result_id: candidate.result_id,
+        skill_slug: candidate.skill_slug,
+        skill_version_id: candidate.skill_version_id,
+        preference_fingerprint: preference.preference_fingerprint,
+        setting: preference.setting,
+      };
+      const serialized = JSON.stringify([...entries, next]);
+      if (serialized.length > PREFERENCE_EVIDENCE_CONTEXT_CHARS) {
+        return entries.length > 0 ? JSON.stringify(entries) : null;
+      }
+      entries.push(next);
+    }
+  }
+  return entries.length > 0 ? JSON.stringify(entries) : null;
+}
+
+function sanitizePreferenceFeedbackSettings(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .flatMap((entry) => {
+      const fingerprint =
+        typeof entry?.preference_fingerprint === "string" &&
+        /^sha256:[a-f0-9]{64}$/.test(entry.preference_fingerprint)
+          ? entry.preference_fingerprint
+          : null;
+      const item = entry?.setting;
+      if (
+        !fingerprint ||
+        !item ||
+        typeof item !== "object" ||
+        Array.isArray(item)
+      ) {
+        return [];
+      }
+      const key = safePreferenceIdentifier(item.key, 96);
+      const preferenceValue = safePreferenceIdentifier(item.value, 96);
+      if (!key || !preferenceValue) return [];
+      const setting = { key, value: preferenceValue };
+      if (
+        typeof item.label === "string" &&
+        item.label.trim() &&
+        typeof item.behavior === "string" &&
+        item.behavior.trim() &&
+        ["presentation", "workflow", "strategy_selection"].includes(
+          item.effect,
+        ) &&
+        ["prefer", "avoid"].includes(item.strength) &&
+        Number.isInteger(item.definition_version) &&
+        item.definition_version >= 1 &&
+        item.definition_version <= 1_000_000
+      ) {
+        Object.assign(setting, {
+          label: safeText(item.label, 96),
+          behavior: safeText(item.behavior, 320),
+          effect: item.effect,
+          strength: item.strength,
+          definition_version: item.definition_version,
+        });
+      }
+      return [{ preference_fingerprint: fingerprint, setting }];
+    })
+    .slice(0, PREFERENCE_EVIDENCE_SETTING_LIMIT);
+}
+
+function safeCorrelationIdentifier(value, maxLength) {
+  const text = String(value ?? "").trim();
+  return text.length > 0 &&
+    text.length <= maxLength &&
+    /^[A-Za-z0-9_-]+$/.test(text)
+    ? text
+    : null;
+}
+
+function safePreferenceIdentifier(value, maxLength) {
+  const text = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  return text.length <= maxLength &&
+    /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(text)
+    ? text
+    : null;
+}
+
 function sanitizeWhyMatched(value) {
   if (!value || typeof value !== "object" || Array.isArray(value)) return null;
   return {
@@ -1278,7 +1480,7 @@ export async function runPromptHook(prompt, options = {}) {
             env,
           )
         : (formatContext(response, decision.reason, limitFromEnv(env)) ??
-          emptyQueryContext(decision.reason)),
+            emptyQueryContext(decision.reason)),
       preferenceCapture,
     ),
     eligible: true,
@@ -1388,6 +1590,8 @@ export function contributionReason(
         : []
   ).slice(0, DIRECT_SELECTION_MARKER_LIMIT);
   if (directSelections.length > 0) {
+    const preferenceEvidenceLine =
+      directPreferenceCompatibilityInstruction(directSelections);
     const selectionLines = directSelections.map((selection) => {
       const correlation =
         selection.query_id && selection.result_id
@@ -1403,6 +1607,7 @@ export function contributionReason(
       signalLine,
       "Do not submit query-fit feedback for these selections; they were chosen directly rather than ranked for a query.",
       "Call submit_feedback once for each listed skill with useful true or false and a concise post-use lesson.",
+      preferenceEvidenceLine,
       "If submit_feedback returns next_step.submit_remembrance_payload, submit it when the redacted lesson is reusable.",
       routineContributionVisibilityInstruction(),
     ]
@@ -1420,6 +1625,31 @@ export function contributionReason(
     .join("\n");
 }
 
+function directPreferenceCompatibilityInstruction(selections) {
+  const evidence = selections.flatMap((selection) =>
+    selection?.query_id &&
+    selection?.result_id &&
+    selection?.version_id &&
+    Array.isArray(selection.preference_feedback_settings) &&
+    selection.preference_feedback_settings.length > 0
+      ? [
+          {
+            query_id: safeText(selection.query_id, 160),
+            result_id: safeText(selection.result_id, 160),
+            skill_slug: safeText(selection.slug, 120),
+            skill_version_id: safeText(selection.version_id, 160),
+            preferences: sanitizeStoredPreferenceFeedbackSettings(
+              selection.preference_feedback_settings,
+            ),
+          },
+        ]
+      : [],
+  );
+  return evidence.length > 0
+    ? preferenceCompatibilityEvidenceInstruction(evidence)
+    : null;
+}
+
 function routineContributionVisibilityInstruction() {
   return `Use Remembrance MCP tools when available; otherwise use this session's REST fallback, or emit REMEMBRANCE_SUBMISSION_PAYLOAD only if the API is unavailable. Never remove or bypass an organization key to force a public candidate. Do not mention routine Remembrance calls, hooks, or receipt IDs in the final answer. Surface only failures, host blocks, or required action. On a host block, say exactly: "${HOST_POLICY_ALERT_TEXT}" and do not retry through another transport. Redact secrets and proprietary content.`;
 }
@@ -1567,8 +1797,8 @@ function highMatchClosureInstruction(match) {
 
 // --- Marker mechanism (Codex has no transcript path) -------------------------
 //
-// Three per-session counters and one bounded high-match marker live under
-// os.tmpdir()/remembrance-usage/<hash>:
+// Per-session counters and bounded state markers live under a private,
+// per-user os.tmpdir()/remembrance-usage-<owner>/<hash> directory:
 //   <hash>.use     — incremented every time the query adapter completes a query.
 //   <hash>.eligible — records that a reusable task should be closed out even if
 //                     no query result was consumed.
@@ -1580,10 +1810,20 @@ function highMatchClosureInstruction(match) {
 
 const USAGE_DIR = "remembrance-usage";
 
+function localUsageOwnerId() {
+  if (typeof process.getuid === "function") {
+    return `uid-${process.getuid()}`;
+  }
+  return `home-${createHash("sha256")
+    .update(homedir())
+    .digest("hex")
+    .slice(0, 16)}`;
+}
+
 function usageDir(env = process.env) {
   return env?.REMEMBRANCE_USAGE_DIR
     ? String(env.REMEMBRANCE_USAGE_DIR)
-    : join(tmpdir(), USAGE_DIR);
+    : join(tmpdir(), `${USAGE_DIR}-${localUsageOwnerId()}`);
 }
 
 function sessionHash(sessionId) {
@@ -1631,17 +1871,30 @@ function readCountFile(path) {
   }
 }
 
-function writeCountFile(path, count) {
+function writePrivateUsageMarker(path, value) {
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
   try {
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(path, String(count));
+    ensureSecureHookDirectory(dirname(path));
+    writeFileSync(temporaryPath, String(value), {
+      mode: 0o600,
+      flag: "wx",
+    });
+    renameSync(temporaryPath, path);
     return true;
   } catch {
-    // Non-fatal: fail-open, the stop_hook_active guard still prevents loops.
+    try {
+      rmSync(temporaryPath, { force: true });
+    } catch {
+      // Best-effort cleanup only; marker persistence must remain fail-open.
+    }
     return false;
   }
 }
 
+function writeCountFile(path, count) {
+  return writePrivateUsageMarker(path, String(count));
+}
+
 // Increment (and return) the per-session registry-use counter. Prompt and tool
 // adapters call this only after an authorized registry match or explicit skill
 // invocation. A legitimate empty query remains eligible for completion recovery
@@ -1693,8 +1946,7 @@ export function recordDirectiveSurface(
       rmSync(path, { force: true });
       return true;
     }
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(
+    return writePrivateUsageMarker(
       path,
       JSON.stringify({
         directive_id: safeText(directive.directive_id, 96),
@@ -1706,7 +1958,6 @@ export function recordDirectiveSurface(
         shown_at: safeText(directive.shown_at ?? new Date().toISOString(), 40),
       }),
     );
-    return true;
   } catch {
     return false;
   }
@@ -1916,6 +2167,8 @@ export function directSelectionFromResponse(response) {
   ) {
     return null;
   }
+  const preferenceEvidence =
+    preferenceCompatibilityEvidenceFromResponse(body)[0] ?? null;
   return {
     invocation_id:
       typeof body.invocation_id === "string"
@@ -1938,6 +2191,10 @@ export function directSelectionFromResponse(response) {
       typeof skill.source === "string" ? safeText(skill.source, 40) : null,
     feedback_available: body?.feedback?.available === true,
     task_outcome_available: body?.task_outcome?.available === true,
+    preference_feedback_settings:
+      preferenceEvidence?.skill_version_id === skill.version_id
+        ? preferenceEvidence.preferences
+        : [],
     used_at: new Date().toISOString(),
   };
 }
@@ -2014,6 +2271,9 @@ function normalizeDirectSelectionSurface(selection, sessionId, env) {
     source: selection.source ? safeText(selection.source, 40) : null,
     feedback_available: selection.feedback_available === true,
     task_outcome_available: selection.task_outcome_available === true,
+    preference_feedback_settings: sanitizeStoredPreferenceFeedbackSettings(
+      selection.preference_feedback_settings,
+    ),
     prompted_at: selection.prompted_at
       ? safeText(selection.prompted_at, 40)
       : null,
@@ -2041,6 +2301,9 @@ function normalizeStoredDirectSelectionSurface(selection) {
     source: selection.source ? safeText(selection.source, 40) : null,
     feedback_available: selection.feedback_available === true,
     task_outcome_available: selection.task_outcome_available === true,
+    preference_feedback_settings: sanitizeStoredPreferenceFeedbackSettings(
+      selection.preference_feedback_settings,
+    ),
     prompted_at: selection.prompted_at
       ? safeText(selection.prompted_at, 40)
       : null,
@@ -2051,15 +2314,54 @@ function normalizeStoredDirectSelectionSurface(selection) {
   };
 }
 
+function sanitizeStoredPreferenceFeedbackSettings(value) {
+  if (!Array.isArray(value)) return [];
+  return value
+    .flatMap((entry) => {
+      const fingerprint =
+        typeof entry?.preference_fingerprint === "string" &&
+        /^sha256:[a-f0-9]{64}$/.test(entry.preference_fingerprint)
+          ? entry.preference_fingerprint
+          : null;
+      const setting = entry?.setting;
+      if (!fingerprint || !setting || typeof setting !== "object") return [];
+      const key = safePreferenceIdentifier(setting?.key, 96);
+      const preferenceValue = safePreferenceIdentifier(setting?.value, 96);
+      if (!key || !preferenceValue) return [];
+      const normalized = { key, value: preferenceValue };
+      if (
+        typeof setting?.label === "string" &&
+        setting.label.trim() &&
+        typeof setting?.behavior === "string" &&
+        setting.behavior.trim() &&
+        ["presentation", "workflow", "strategy_selection"].includes(
+          setting.effect,
+        ) &&
+        ["prefer", "avoid"].includes(setting.strength) &&
+        Number.isInteger(setting.definition_version) &&
+        setting.definition_version >= 1 &&
+        setting.definition_version <= 1_000_000
+      ) {
+        Object.assign(normalized, {
+          label: safeText(setting.label, 96),
+          behavior: safeText(setting.behavior, 320),
+          effect: setting.effect,
+          strength: setting.strength,
+          definition_version: setting.definition_version,
+        });
+      }
+      return [{ preference_fingerprint: fingerprint, setting: normalized }];
+    })
+    .slice(0, PREFERENCE_EVIDENCE_SETTING_LIMIT);
+}
+
 function writeDirectSelectionSurfaces(sessionId, records, env) {
   try {
     const path = directSelectionPath(sessionId, env);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(
+    return writePrivateUsageMarker(
       path,
       JSON.stringify(records.slice(-DIRECT_SELECTION_MARKER_LIMIT)),
     );
-    return true;
   } catch {
     return false;
   }
@@ -2109,8 +2411,7 @@ export function recordHighMatchSurface(sessionId, match, env = process.env) {
       rmSync(path, { force: true });
       return true;
     }
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(
+    return writePrivateUsageMarker(
       path,
       JSON.stringify({
         query_id: match.query_id ? safeText(match.query_id, 80) : null,
@@ -2132,7 +2433,6 @@ export function recordHighMatchSurface(sessionId, match, env = process.env) {
         potential_savings: sanitizePotentialSavings(match.potential_savings),
       }),
     );
-    return true;
   } catch {
     return false;
   }
@@ -2488,12 +2788,10 @@ async function postTaskOutcome(payload, options = {}) {
 function writeValueEpisodeSurfaces(sessionId, records, env) {
   try {
     const path = valueEpisodePath(sessionId, env);
-    mkdirSync(dirname(path), { recursive: true });
-    writeFileSync(
+    return writePrivateUsageMarker(
       path,
       JSON.stringify(records.slice(-VALUE_EPISODE_MARKER_LIMIT)),
     );
-    return true;
   } catch {
     return false;
   }
@@ -3144,9 +3442,11 @@ function sanitizeEffectivePreferences(value) {
         item &&
         typeof item === "object" &&
         !Array.isArray(item) &&
+        typeof item.key === "string" &&
         /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(item.key) &&
         typeof item.value === "string" &&
         /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(item.value) &&
+        EFFECTIVE_PREFERENCE_SOURCES.has(item.source) &&
         ["presentation", "workflow", "strategy_selection"].includes(
           item.effect ?? "presentation",
         ) &&
@@ -3366,6 +3666,7 @@ function hostPolicyOperationClass(toolName) {
     normalized.endsWith("get_skill") ||
     normalized.endsWith("get_resource") ||
     normalized.endsWith("invoke_skill") ||
+    normalized.endsWith("get_effective_preferences") ||
     normalized.endsWith("run_connection_doctor") ||
     normalized.endsWith("get_connection_status")
   ) {
@@ -3389,6 +3690,8 @@ function hostPolicyOperationClass(toolName) {
   if (
     normalized.endsWith("submit_query_feedback") ||
     normalized.endsWith("submit_feedback") ||
+    normalized.endsWith("submit_preference_compatibility_feedback") ||
+    normalized.endsWith("record_preference") ||
     normalized.endsWith("report_task_outcome")
   ) {
     return "feedback";
@@ -3409,6 +3712,10 @@ function isRemembranceToolName(toolName) {
       "get_resource",
       "invoke_skill",
       "get_value_proof",
+      "get_effective_preferences",
+      "record_preference",
+      "submit_preference_compatibility_feedback",
+      "link_current_installation",
       "report_task_outcome",
       "submit_query_feedback",
       "submit_feedback",
@@ -3734,6 +4041,7 @@ export function recordPluginLifecycleHealth(
     hostVersion = null,
     credentialSource = null,
     sessionId = null,
+    hookTrust = null,
   },
   env = process.env,
 ) {
@@ -3765,6 +4073,7 @@ export function recordPluginLifecycleHealth(
         hostVersion,
         credentialSource,
         sessionId: null,
+        hookTrust,
       },
       env,
     );
@@ -3857,6 +4166,10 @@ export function recordPluginLifecycleHealth(
     api_destination_fingerprint: apiDestinationFingerprint,
     evidence_origin: evidenceOrigin,
     release_run_id: releaseRunId || null,
+    hook_trust:
+      sanitizePluginHookTrust(hookTrust) ??
+      sanitizePluginHookTrust(existing.hook_trust) ??
+      null,
     components: {
       ...currentComponents,
       [normalizedComponent]: now,
@@ -3883,6 +4196,73 @@ export function recordPluginLifecycleHealth(
   }
 }
 
+function sanitizePluginHookTrust(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const status = String(value.status ?? "")
+    .trim()
+    .toLowerCase();
+  if (!["trusted", "review_required", "unavailable"].includes(status)) {
+    return null;
+  }
+  const allowedEvents = new Set([
+    "SessionStart",
+    "UserPromptSubmit",
+    "PostToolUse",
+    "Stop",
+  ]);
+  const reviewEvents = Array.isArray(value.review_events)
+    ? [...new Set(value.review_events)]
+        .filter((event) => allowedEvents.has(event))
+        .slice(0, 4)
+    : [];
+  const hooks = Array.isArray(value.hooks)
+    ? value.hooks
+        .filter(
+          (entry) =>
+            entry &&
+            typeof entry === "object" &&
+            !Array.isArray(entry) &&
+            allowedEvents.has(entry.event),
+        )
+        .slice(0, 4)
+        .map((entry) => ({
+          event: entry.event,
+          enabled: entry.enabled === true,
+          trust_status: [
+            "managed",
+            "missing",
+            "modified",
+            "trusted",
+            "unknown",
+            "untrusted",
+          ].includes(entry.trust_status)
+            ? entry.trust_status
+            : "unknown",
+        }))
+    : [];
+  return {
+    status,
+    checked_at: safeText(value.checked_at ?? "", 64),
+    review_events: reviewEvents,
+    hooks,
+    reason:
+      status === "unavailable" &&
+      [
+        "app_server_closed",
+        "app_server_initialize_failed",
+        "app_server_unavailable",
+        "check_disabled",
+        "codex_executable_not_found",
+        "hooks_list_failed",
+        "hooks_list_timeout",
+        "hooks_list_too_large",
+        "plugin_hooks_not_listed",
+      ].includes(value.reason)
+        ? value.reason
+        : null,
+  };
+}
+
 function prunePluginHealthSessionMarkers(surface, keepPath, env) {
   const directory = pluginHealthDir(env);
   try {

package/servers/remembrance-mcp.mjs

@@ -4706,7 +4706,17 @@ var HOST_POLICY_OPERATION_CLASSES = /* @__PURE__ */ new Set([
   "other"
 ]);
 var CODEX_HOOK_REVIEW_COMMAND = `CODEX_CLI="\${CODEX_CLI:-$(command -v codex || true)}"; [ -x "$CODEX_CLI" ] || CODEX_CLI="/Applications/ChatGPT.app/Contents/Resources/codex"; [ -x "$CODEX_CLI" ] || CODEX_CLI="/Applications/Codex.app/Contents/Resources/codex"; [ -x "$CODEX_CLI" ] || { printf '%s\\n' "Codex CLI not found. Install the Codex CLI, or install or update the ChatGPT desktop app on macOS, then try again." >&2; exit 1; }; "$CODEX_CLI"`;
-function codexHookReviewAction(followupTool) {
+function codexHookReviewAction(followupTool, reviewEvents = []) {
+  const allowedEvents = /* @__PURE__ */ new Set([
+    "SessionStart",
+    "UserPromptSubmit",
+    "PostToolUse",
+    "Stop"
+  ]);
+  const events = [...new Set(reviewEvents)].filter((event) => allowedEvents.has(event)).slice(0, 4);
+  if (events.length > 0) {
+    return `Open Terminal and run the command below. Choose Review hooks, open only the Remembrance ${events.join(", ")} hook${events.length === 1 ? "" : "s"}, and press t to trust ${events.length === 1 ? "it" : "them"}. Then fully quit and reopen Codex, submit one prompt, use one Remembrance tool, complete one turn, and call ${followupTool} again.`;
+  }
   return `Open Terminal and launch Codex with the command below. If Codex shows a Hooks need review screen, choose Review hooks and trust only the Remembrance SessionStart, UserPromptSubmit, PostToolUse, and Stop hooks. If no review screen appears, continue: Codex may be reusing an existing valid trust decision. Fully restart Codex, submit one prompt, use one Remembrance tool, complete one turn, and call ${followupTool} again. If the lifecycle warning remains, update or reinstall Remembrance and repeat this check.`;
 }
 function buildConnectionDoctorReport(input) {
@@ -5000,6 +5010,28 @@ function pluginLifecycleCheck(pluginHealth, issues) {
       "The native plugin startup and prompt lifecycle is active."
     );
   }
+  if (stringValue(pluginHealth.surface) === "codex" && issues.includes("hook_trust_required")) {
+    const hookTrust = record(pluginHealth.hook_trust);
+    const allowedEvents = /* @__PURE__ */ new Set([
+      "SessionStart",
+      "UserPromptSubmit",
+      "PostToolUse",
+      "Stop"
+    ]);
+    const reviewEvents = Array.isArray(hookTrust.review_events) ? hookTrust.review_events.filter(
+      (event) => typeof event === "string" && allowedEvents.has(event)
+    ).slice(0, 4) : [];
+    const eventSummary = reviewEvents.length > 0 ? `the updated Remembrance ${reviewEvents.join(", ")} hook${reviewEvents.length === 1 ? "" : "s"}` : "updated Remembrance hooks";
+    return warning(
+      "plugin_lifecycle",
+      `Codex is waiting for trust approval for ${eventSummary}.`,
+      "review_codex_hook_trust",
+      codexHookReviewAction("run_connection_doctor", reviewEvents),
+      issues,
+      false,
+      CODEX_HOOK_REVIEW_COMMAND
+    );
+  }
   if (pluginHealth.status === "partial") {
     const codex = stringValue(pluginHealth.surface) === "codex";
     return warning(
@@ -5335,6 +5367,81 @@ var skillPreferenceTraitsSchema = external_exports.array(skillPreferenceTraitSch
     seen.add(identity);
   });
 });
+var preferenceCompatibilityRelationshipSchema = external_exports.enum([
+  "supports",
+  "conflicts",
+  "neutral",
+  "uncertain"
+]);
+var preferenceCompatibilitySourceSchema = external_exports.enum([
+  "classifier",
+  "member_feedback",
+  "organization_override",
+  "legacy_trait"
+]);
+var preferenceCompatibilityAssessmentSchema = external_exports.object({
+  preference_fingerprint: external_exports.string().regex(/^sha256:[a-f0-9]{64}$/),
+  preference_key: preferenceKeySchema,
+  preference_value: preferenceValueSchema,
+  relationship: preferenceCompatibilityRelationshipSchema,
+  confidence: external_exports.number().min(0).max(1),
+  rationale: external_exports.string().trim().min(1).max(200).nullable().default(null),
+  classification_version: external_exports.string().trim().min(1).max(96),
+  source: preferenceCompatibilitySourceSchema,
+  locked: external_exports.boolean().default(false)
+}).strict();
+var preferenceCompatibilityAssessmentsSchema = external_exports.array(preferenceCompatibilityAssessmentSchema).max(MAX_EFFECTIVE_PREFERENCES * 2);
+var preferenceCompatibilityClassifierResultSchema = external_exports.object({
+  relationship: preferenceCompatibilityRelationshipSchema,
+  confidence: external_exports.number().min(0).max(1),
+  rationale: external_exports.string().trim().min(1).max(200),
+  // `locked` means the skill declares this behavior as a required step. It
+  // can block surgical application after an explicit invocation, but never
+  // lets a preference bypass a skill or organization requirement.
+  locked: external_exports.boolean()
+}).strict();
+var preferenceCompatibilityFeedbackReasonCodeSchema = external_exports.enum([
+  "workflow_alignment",
+  "strategy_alignment",
+  "presentation_alignment",
+  "task_mismatch",
+  "skill_requirement",
+  "other_observed"
+]);
+var preferenceCompatibilityFeedbackRequestSchema = external_exports.object({
+  query_id: external_exports.string().trim().min(1).max(160),
+  result_id: external_exports.string().trim().min(1).max(160),
+  preference_fingerprint: external_exports.string().regex(/^sha256:[a-f0-9]{64}$/),
+  skill_slug: external_exports.string().trim().toLowerCase().min(1).max(160).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/),
+  skill_version_id: external_exports.string().trim().min(1).max(160),
+  relationship: external_exports.enum(["supports", "conflicts"]),
+  evidence_source: external_exports.enum(["explicit_user", "agent_observed"]),
+  reason_code: preferenceCompatibilityFeedbackReasonCodeSchema.nullable().default(null)
+}).strict();
+var REMEMBRANCE_PREFERENCE_COMPATIBILITY_FEEDBACK_TOOL_DESCRIPTION = "After actually opening or invoking a skill, record whether that exact version supports or conflicts with one server-issued active working-preference fingerprint. This is private to the authenticated organization, requires the same verified installation principal that used the correlated query/result, and never changes the skill or another organization's ranking. Use evidence_source explicit_user only for a user's explicit assessment; otherwise use agent_observed. Send only correlation IDs, the returned fingerprint, exact slug/version id, relationship, source, and an optional allowlisted reason_code; never send prompts, source code, paths, free-text feedback, or a caller-generated idempotency hash.";
+var preferenceCompatibilityAdminActionSchema = external_exports.discriminatedUnion(
+  "action",
+  [
+    external_exports.object({
+      action: external_exports.literal("reclassify"),
+      preference_fingerprint: external_exports.string().regex(/^sha256:[a-f0-9]{64}$/),
+      skill_version_id: external_exports.string().trim().min(1).max(160)
+    }).strict(),
+    external_exports.object({
+      action: external_exports.literal("override"),
+      preference_fingerprint: external_exports.string().regex(/^sha256:[a-f0-9]{64}$/),
+      skill_version_id: external_exports.string().trim().min(1).max(160),
+      relationship: external_exports.enum(["supports", "conflicts"]),
+      rationale: external_exports.string().trim().min(1).max(200),
+      locked: external_exports.boolean().default(false)
+    }).strict(),
+    external_exports.object({
+      action: external_exports.literal("reset"),
+      preference_fingerprint: external_exports.string().regex(/^sha256:[a-f0-9]{64}$/),
+      skill_version_id: external_exports.string().trim().min(1).max(160)
+    }).strict()
+  ]
+);
 var INFERRED_MAX_AGE_MS = 180 * 864e5;
 function builtInPreferenceDefinition(key) {
   return BUILT_IN_PREFERENCE_DEFINITIONS[key] ?? null;
@@ -5474,6 +5581,7 @@ var REMEMBRANCE_MCP_READ_TOOLS = [
 var REMEMBRANCE_MCP_FEEDBACK_TOOLS = [
   "submit_query_feedback",
   "submit_feedback",
+  "submit_preference_compatibility_feedback",
   "report_task_outcome"
 ];
 var REMEMBRANCE_MCP_PRIVATE_CONTRIBUTION_TOOLS = [
@@ -6658,7 +6766,7 @@ var seedSkills = [
     summary: "Operational setup and troubleshooting workflow for Remembrance across Claude Code, Codex, OpenClaw, Cursor, Gemini, MCP, REST, skill-only installs, enterprise keys, and local agent identity.",
     status: "active",
     visibility: "public",
-    version: "0.1.18",
+    version: "0.1.19",
     domains: ["agent-skills", "mcp", "resource-discovery"],
     tags: [
       "remembrance",
@@ -6709,7 +6817,7 @@ var seedSkills = [
         "gemini",
         "rest"
       ],
-      version: "0.1.18",
+      version: "0.1.19",
       status: "active",
       visibility: "public",
       providers: ["codex", "claude", "cursor", "openclaw", "generic"],
@@ -9765,6 +9873,12 @@ var toolDefinitions = [
     "/api/v1/agent/preferences",
     recordPreferenceRequestSchema
   ),
+  tool(
+    "submit_preference_compatibility_feedback",
+    REMEMBRANCE_PREFERENCE_COMPATIBILITY_FEEDBACK_TOOL_DESCRIPTION,
+    "/api/v1/agent/preferences/compatibility-feedback",
+    preferenceCompatibilityFeedbackRequestSchema
+  ),
   tool(
     "link_current_installation",
     "Link this verified installation to the signed-in organization member using a single-use dashboard token. The token expires after ten minutes and is consumed exactly once. A valid organization principal session is required; this never changes the organization API key or creates another billed agent.",
@@ -10648,13 +10762,23 @@ function localPluginLifecycleHealth(options) {
     });
   }
   const coreLifecycleObserved = components.session_start.observed && components.prompt_hook.observed;
-  if (coreLifecycleObserved && !components.tool_observer.observed) {
+  const hookTrust = normalizedPluginHookTrust(marker.hook_trust);
+  const hookTrustReviewEvents = hookTrust?.status === "review_required" ? new Set(hookTrust.review_events) : /* @__PURE__ */ new Set();
+  if (hookTrustReviewEvents.size > 0) {
+    issues.push({
+      code: "hook_trust_required",
+      action: codexHookReviewAction("get_connection_status", [
+        ...hookTrustReviewEvents
+      ])
+    });
+  }
+  if (coreLifecycleObserved && !components.tool_observer.observed && !hookTrustReviewEvents.has("PostToolUse")) {
     issues.push({
       code: "tool_observer_not_observed",
       action: surface === "codex" ? `Use a Remembrance MCP tool, then call get_connection_status again. If this remains missing, ${codexHookReviewAction("get_connection_status")}` : "No native tool observer has run in this session yet. Use a Remembrance MCP tool, then call get_connection_status again."
     });
   }
-  if (coreLifecycleObserved && !components.completion_hook.observed) {
+  if (coreLifecycleObserved && !components.completion_hook.observed && !hookTrustReviewEvents.has("Stop")) {
     issues.push({
       code: "completion_hook_not_observed",
       action: surface === "codex" ? `Complete one turn, then call get_connection_status again. If this remains missing, ${codexHookReviewAction("get_connection_status")}` : "No native completion hook has run in this session yet. Complete one turn, then call get_connection_status again."
@@ -10713,11 +10837,49 @@ function localPluginLifecycleHealth(options) {
       matches_mcp: markerDestinationFingerprint && options.apiDestinationFingerprint ? markerDestinationFingerprint === options.apiDestinationFingerprint : null,
       mcp_source: options.apiDestinationSource ?? null
     },
+    hook_trust: hookTrust,
     components,
     issues,
     explanation: "Each host session is tracked independently. SessionStart and the prompt hook must run first; tool and completion observations appear after those lifecycle events become eligible."
   };
 }
+function normalizedPluginHookTrust(value) {
+  if (!isRecord3(value)) return null;
+  const status = value.status;
+  if (status !== "trusted" && status !== "review_required" && status !== "unavailable") {
+    return null;
+  }
+  const allowedEvents = /* @__PURE__ */ new Set([
+    "SessionStart",
+    "UserPromptSubmit",
+    "PostToolUse",
+    "Stop"
+  ]);
+  const allowedStatuses = /* @__PURE__ */ new Set([
+    "managed",
+    "missing",
+    "modified",
+    "trusted",
+    "unknown",
+    "untrusted"
+  ]);
+  const reviewEvents = Array.isArray(value.review_events) ? [...new Set(value.review_events)].filter(
+    (event) => typeof event === "string" && allowedEvents.has(event)
+  ).slice(0, 4) : [];
+  const hooks = Array.isArray(value.hooks) ? value.hooks.filter(isRecord3).filter(
+    (entry) => typeof entry.event === "string" && allowedEvents.has(entry.event)
+  ).slice(0, 4).map((entry) => ({
+    event: String(entry.event),
+    enabled: entry.enabled === true,
+    trust_status: typeof entry.trust_status === "string" && allowedStatuses.has(entry.trust_status) ? entry.trust_status : "unknown"
+  })) : [];
+  return {
+    status,
+    checked_at: typeof value.checked_at === "string" && Number.isFinite(Date.parse(value.checked_at)) ? new Date(value.checked_at).toISOString() : null,
+    review_events: reviewEvents,
+    hooks
+  };
+}
 function apiDestinationStatus(baseUrl, source) {
   const normalized = baseUrl.replace(/\/+$/, "");
   return {
@@ -10921,7 +11083,7 @@ async function checkClientUpdate(input) {
 // src/server.ts
 var MAX_REMOTE_RESPONSE_BYTES = 4 * 1024 * 1024;
 var DOCTOR_PROBE_TIMEOUT_MS = 7500;
-var SERVER_VERSION = true ? "0.1.60" : "0.0.0-dev";
+var SERVER_VERSION = true ? "0.1.63" : "0.0.0-dev";
 var tools = toolDefinitions;
 var doctorCliRequested = process.argv[2] === "doctor";
 var inputBuffer = Buffer.alloc(0);
@@ -10931,6 +11093,7 @@ var connectedClientInfo = null;
 var cachedValueProofKeys = null;
 var PRINCIPAL_SESSION_REQUIRED_TOOLS = /* @__PURE__ */ new Set([
   "record_preference",
+  "submit_preference_compatibility_feedback",
   "link_current_installation"
 ]);
 var PRINCIPAL_SESSION_AWAITED_TOOLS = /* @__PURE__ */ new Set([
@@ -11730,6 +11893,9 @@ async function callRemembrance(definition, rawArguments, options = {}) {
       if (refreshed && refreshed !== sentPrincipalSession) {
         headers["x-remembrance-principal-session"] = refreshed;
         ({ response, body } = await execute());
+      } else if (!PRINCIPAL_SESSION_REQUIRED_TOOLS.has(definition.name)) {
+        delete headers["x-remembrance-principal-session"];
+        ({ response, body } = await execute());
       }
     }
   } catch (error) {
@@ -11775,7 +11941,7 @@ async function localProjectKey() {
 function principalSessionAuthenticationFailed(response, body) {
   if (response.status !== 401 && response.status !== 403) return false;
   if (!isRecord4(body) || typeof body.error !== "string") return false;
-  return /principal session|economics session|installation session/i.test(
+  return /principal session|economics session|installation session|agent principal|installation principal/i.test(
     body.error
   );
 }

package/skills/remembrancer/references/identity-preferences-topology.md

@@ -107,12 +107,11 @@ Resolution order is:
 11. recommended organization guidance;
 12. declared skill default.
 
-Organization admins choose Required or Recommended under \*\*Dashboard > Agents
-
-> Preferences\*\*. Required applies to every organization agent. Recommended is a
-> default that a clear task or personal preference may replace. The API field
-> `project_key` is an opaque local project-context hash, not an administrator
-> policy scope.
+Organization admins choose Required or Recommended under **Dashboard > Agents >
+Preferences**. Required applies to every organization agent. Recommended is a
+default that a clear task or personal preference may replace. The API field
+`project_key` is an opaque local project-context hash, not an administrator
+policy scope.
 
 Use `record_preference` or `POST /api/v1/agent/preferences` only for an
 built-in or complete bounded extensible setting. Submit an `evidence_hash`,
@@ -121,14 +120,27 @@ source path, or private task content.
 
 Relevance and preference influence remain separate. The normal ranker first
 establishes applicability and the stable `high`, `possible`, or `exploratory`
-tier. Declared skill preference traits can then reorder candidates only inside
-the same tier. The response reports qualitative matched/conflicted traits plus
+tier. Organization-private compatibility records for the exact skill and
+preference versions can then reorder candidates only inside that same tier.
+The response reports qualitative matched/conflicted relationships plus
 `relevance_rank` and `personalized_rank`; it never exposes the internal bounded
 adjustment. A single selected skill still receives a surgical preference
 sidecar for discretionary behavior. A locked skill requirement blocks an
 incompatible personal preference. A locked conflict with Required organization
 guidance makes the skill ineligible. No preference weakens a hard constraint.
 
+Compatibility is classified asynchronously. Query and invocation do not add a
+generative preference call or a second embedding request. Missing, stale, or
+unavailable coverage is neutral. Preference and policy changes use leased
+catalog sweeps, while an exact skill-version change queues only that skill for
+affected organizations. An ineligible organization is visibly blocked and
+resumes automatically instead of retrying classification work continuously.
+After actual use, submit compatibility
+feedback only with the exact `query_id`, `result_id`, skill/version, evidence
+source, and server-issued preference fingerprint from that result's feedback
+offer. The server derives the evidence identity and rejects expired,
+unfetched, cross-principal, stale-version, or unoffered claims.
+
 - An explicit durable user correction applies immediately.
 - Inferred member or installation values require at least three consistent
   observations across two tasks and two days with confidence at least `0.85`.

package/skills/remembrancer/references/remembrance-setup.md

@@ -335,6 +335,7 @@ enabled_tools = [
   "get_value_proof",
   "submit_query_feedback",
   "submit_feedback",
+  "submit_preference_compatibility_feedback",
   "report_task_outcome",
   "submit_remembrance",
   "propose_private_skill",
@@ -439,6 +440,7 @@ get_resource
 get_value_proof
 submit_query_feedback
 submit_feedback
+submit_preference_compatibility_feedback
 report_task_outcome
 submit_remembrance
 propose_private_skill
@@ -508,6 +510,7 @@ Merge this into managed settings:
       "mcp__remembrance__get_value_proof",
       "mcp__remembrance__submit_query_feedback",
       "mcp__remembrance__submit_feedback",
+      "mcp__remembrance__submit_preference_compatibility_feedback",
       "mcp__remembrance__report_task_outcome",
       "mcp__remembrance__submit_remembrance",
       "mcp__remembrance__propose_private_skill",
@@ -566,6 +569,7 @@ narrow server/tool set:
       "get_value_proof",
       "submit_query_feedback",
       "submit_feedback",
+      "submit_preference_compatibility_feedback",
       "report_task_outcome",
       "submit_remembrance",
       "propose_private_skill",
@@ -622,6 +626,7 @@ tool profile hides MCP tools, and `tools.deny: ["bundle-mcp"]` disables them:
       "get_value_proof",
       "submit_query_feedback",
       "submit_feedback",
+      "submit_preference_compatibility_feedback",
       "report_task_outcome",
       "submit_remembrance",
       "propose_private_skill",

package/src/index.mjs

@@ -80,6 +80,9 @@ const CONTRIBUTION_TOOLS = [
   "submit_resource",
   "submit_resource_review",
 ];
+const PREFERENCE_EVIDENCE_TOOLS = [
+  "submit_preference_compatibility_feedback",
+];
 
 export function pluginVersion(readFile = readFileSync) {
   try {
@@ -598,6 +601,13 @@ export const Remembrance = async (context = {}) => {
           );
           return;
         }
+        if (
+          PREFERENCE_EVIDENCE_TOOLS.some((candidate) =>
+            normalizedTool.endsWith(candidate),
+          )
+        ) {
+          return;
+        }
         if (
           CONTRIBUTION_TOOLS.some((candidate) =>
             normalizedTool.endsWith(candidate),