@remembrance-ai/opencode-plugin 0.1.45

package/scripts/hook-core.mjs

@@ -0,0 +1,3027 @@
+#!/usr/bin/env node
+// Runtime-agnostic Remembrance hook core.
+//
+// This module holds the shared logic that both Codex adapters
+// (query-on-prompt.mjs, contribute-on-stop.mjs) build on, so those adapters are
+// thin: they only read the runtime's stdin JSON, call into here, and print the
+// runtime's expected stdout shape. Everything here is Node-builtins-only and
+// fail-open by design.
+//
+// Ported from packages/claude-code-plugin/scripts/{query-on-prompt,contribute-on-stop}.mjs.
+// Key difference from the Claude plugin: Codex's Stop payload has NO transcript
+// path, so we cannot count registry consumption by scanning a transcript.
+// Instead the prompt adapter records completed queries and eligible reusable
+// tasks separately. The Stop adapter compares those counters with a
+// last-prompted sentinel — the same count-sentinel pattern the Claude hook uses,
+// but driven by markers instead of transcript scans.
+
+import { createHash, randomBytes } from "node:crypto";
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import process from "node:process";
+
+const DEFAULT_API_URL = "https://remembrance.dev";
+const DEFAULT_LIMIT = 3;
+const DEFAULT_TIMEOUT_MS = 2000;
+const DEFAULT_DIRECTIVE_EVENT_TIMEOUT_MS = 750;
+const DIRECTIVE_MARKER_TTL_MS = 30 * 60 * 1000;
+const MAX_SUMMARY_CHARS = 1200;
+const MAX_CONTEXT_CHARS = 4000;
+const MAX_CONTEXT_FIELD_CHARS = 280;
+const MAX_DIRECTIVE_CHARS = 900;
+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 PLUGIN_HEALTH_DIR = "remembrance-plugin-health";
+const PLUGIN_HEALTH_COMPONENTS = new Set([
+  "session_start",
+  "prompt_hook",
+  "tool_observer",
+  "completion_hook",
+]);
+const PLUGIN_HEALTH_SURFACES = new Set([
+  "codex",
+  "claude_code",
+  "cursor",
+  "openclaw",
+  "vs_code",
+  "opencode",
+]);
+
+const SERVICE_PATTERNS = [
+  /\b(vercel|heroku|netlify|cloudflare|aws|gcp|azure)\b/i,
+  /\b(github actions?|circleci|gitlab ci|buildkite|jenkins)\b/i,
+  /\b(stripe|x402|mpp|model payment protocol|mcp servers?)\b/i,
+  /\b(openai|anthropic|claude|cursor|codex|voyage|mongodb atlas)\b/i,
+];
+
+const TOOL_PATTERNS = [
+  /\b(next\.?js|turbopack|webpack|vite|react|prisma|drizzle)\b/i,
+  /\b(esbuild|playwright|vitest|jest|typescript|node\.?js|npm)\b/i,
+  /\b(mongodb|redis|bullmq|atlas vector search)\b/i,
+];
+
+const WORKFLOW_PATTERNS = [
+  /\b(deploy|deployment|migrate|migration|ci\/cd|ci|pipeline)\b/i,
+  /\b(payment integration|schema upgrade|observability|monitoring)\b/i,
+  /\b(build error|release|rollback|provision|backfill)\b/i,
+];
+
+const UI_PATTERNS = [
+  /\b(web ?ui|ux|usability|accessibility|a11y|responsive|frontend|front-end)\b/i,
+  /\b(dashboard|admin (page|panel|surface)|review card|settings layout)\b/i,
+  /\b(layout|nav(igation| bar| panel)?|sidebar|modal|tooltip|popover)\b/i,
+  /\b(tailwind|styling|component|button|form design|redesign|declutter|design system)\b/i,
+];
+
+// Short action prompts often depend entirely on earlier conversation. The hook
+// cannot safely reconstruct that context in every runtime, but it can make the
+// agent (which does have the thread) perform the missing full-context query.
+// Keep these anchored and action-oriented so ordinary prose does not become a
+// noisy auto-query trigger.
+const CONTEXTUAL_CONTINUATION_PATTERNS = [
+  /^\s*(?:continue|proceed|go ahead|do it|try again|one more pass)\s*[.!?]*\s*$/i,
+  /^\s*(?:fix|address|resolve|implement|apply|tackle|clean up)\s+(?:all\s+)?(?:these|those|the|your)\s+(?:issues|findings|comments|changes|fixes|recommendations|items)\b/i,
+  /^\s*(?:review|check|inspect|look at|take a look at)\s+(?:the\s+)?(?:latest|last|new|recent|remaining)\s+(?:changes?|commits?|updates?|failure|issues?)\b/i,
+  /^\s*(?:how(?:'s| is) it looking|does this look|what about now)\b/i,
+  /^\s*(?:run|rerun)\s+(?:it|that|the tests?|the checks?)\b/i,
+];
+
+const EXPLICIT_SKILL_REFERENCE_PATTERNS = [
+  /\bremembrance:\/\/skills\/[^\s"'<>]+/i,
+  /\/remembrance:use\b/i,
+  /\binvoke_skill\b/i,
+  /\b(?:use|invoke|open|load|select)\s+(?:the\s+)?remembrance\s+skill(?:\s+(?:named|called))?\s+[`"']?[a-z0-9][a-z0-9._-]*[`"']?/i,
+  /\b(?:use|invoke|open|load|select)\s+(?:the\s+)?skill\s+(?:named|called)\s+[`"']?[a-z0-9][a-z0-9._-]*[`"']?\s+(?:from|in)\s+remembrance\b/i,
+];
+
+const SKIP_PATTERNS = [
+  /\b(general web search|search the web|google this|look up current facts?)\b/i,
+  /^\s*(what|who|when|where)\s+(is|are|was|were)\b/i,
+  /\b(one[- ]off fact|private scratch memory|brainstorm)\b/i,
+];
+
+const SECRET_PATTERNS = [
+  /\b(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9_-]{12,}\b/g,
+  /\bsk-proj-[A-Za-z0-9_-]{12,}\b/g,
+  /\bsk-[A-Za-z0-9_-]{20,}\b/g,
+  /\bgithub_pat_[A-Za-z0-9_]{20,}\b/g,
+  /\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g,
+  /\bxox[abp]-[A-Za-z0-9-]{20,}\b/g,
+  /\b(?:AKIA|ASIA)[0-9A-Z]{16}\b/g,
+  /\bya29\.[A-Za-z0-9_-]{20,}\b/g,
+  /\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/g,
+  /\bAIza[0-9A-Za-z_-]{16,}\b/g,
+  /\b(Bearer\s+)[A-Za-z0-9._~+/=-]{12,}\b/gi,
+  /\b(?:aws_secret_access_key|aws_secret_key|secret_access_key)\s*[:=]\s*["']?[A-Za-z0-9/+=]{32,}["']?/gi,
+  /\b(password|secret|token|api[_-]?key)\s*[:=]\s*["']?[^"'\s]+/gi,
+  /\b(?:mongodb(?:\+srv)?|redis(?:s)?|postgres(?:ql)?):\/\/[^\s"'<>]+/gi,
+  /\bhttps?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0|10\.\d+\.\d+\.\d+|192\.168\.\d+\.\d+|172\.(?:1[6-9]|2\d|3[0-1])\.\d+\.\d+)[^\s)"']*/gi,
+  /\bhttps?:\/\/[^/\s)"']*(?:\.internal|\.local|\.corp|\.onion)(?::\d+)?[^\s)"']*/gi,
+];
+
+// --- Trigger heuristic -------------------------------------------------------
+
+export function shouldQueryPrompt(prompt) {
+  const normalized = String(prompt ?? "").trim();
+  if (!normalized || normalized.length < 8) {
+    return { likely_match: false, reason: "empty_or_too_short" };
+  }
+  if (
+    EXPLICIT_SKILL_REFERENCE_PATTERNS.some((pattern) =>
+      pattern.test(normalized),
+    )
+  ) {
+    return { likely_match: false, reason: "explicit_skill_reference" };
+  }
+  if (SKIP_PATTERNS.some((pattern) => pattern.test(normalized))) {
+    return { likely_match: false, reason: "skip_pattern" };
+  }
+  const matches = [
+    ...SERVICE_PATTERNS.map((pattern) => [pattern, "external_service"]),
+    ...TOOL_PATTERNS.map((pattern) => [pattern, "tool_or_framework"]),
+    ...WORKFLOW_PATTERNS.map((pattern) => [pattern, "workflow_shape"]),
+    ...UI_PATTERNS.map((pattern) => [pattern, "ui_or_dashboard_work"]),
+  ];
+  for (const [pattern, reason] of matches) {
+    if (pattern.test(normalized)) {
+      return { likely_match: true, reason };
+    }
+  }
+  if (/\b(integrate|integration|configure|setup|set up)\b/i.test(normalized)) {
+    return { likely_match: true, reason: "third_party_integration" };
+  }
+  return { likely_match: false, reason: "no_trigger_match" };
+}
+
+export function isContextualContinuationPrompt(prompt) {
+  const normalized = String(prompt ?? "").trim();
+  if (
+    !normalized ||
+    SKIP_PATTERNS.some((pattern) => pattern.test(normalized)) ||
+    EXPLICIT_SKILL_REFERENCE_PATTERNS.some((pattern) =>
+      pattern.test(normalized),
+    )
+  ) {
+    return false;
+  }
+  return CONTEXTUAL_CONTINUATION_PATTERNS.some((pattern) =>
+    pattern.test(normalized),
+  );
+}
+
+// --- Redaction ---------------------------------------------------------------
+
+export function redactPrompt(prompt) {
+  let redacted = String(prompt ?? "");
+  for (const pattern of SECRET_PATTERNS) {
+    redacted = redacted.replace(pattern, (match, prefix) => {
+      if (typeof prefix === "string" && /^Bearer\s+/i.test(prefix)) {
+        return `${prefix}[redacted-token]`;
+      }
+      if (/^https?:\/\//i.test(match)) {
+        return "[redacted-private-url]";
+      }
+      return "[redacted-secret]";
+    });
+  }
+  return redacted;
+}
+
+// --- Query payload -----------------------------------------------------------
+
+// Canonical (Codex) agent identity. "codex" must be a value the server's
+// agentProviderSchema accepts — a non-enum provider (the old "openai") makes the
+// /api/v1/agent/query request fail validation, so the fail-open hook silently
+// injects nothing. Other runtimes override via runQuery's identity/userAgent
+// options; the Claude adapter builds its own payload with its own identity.
+export const DEFAULT_AGENT_IDENTITY = { provider: "codex", model: "codex" };
+export const DEFAULT_USER_AGENT = "@remembrance/codex-plugin";
+
+export function buildQueryPayload(
+  prompt,
+  env = process.env,
+  identity = DEFAULT_AGENT_IDENTITY,
+  clientContext = null,
+) {
+  const redacted = redactPrompt(prompt).trim();
+  const summary =
+    redacted.length <= MAX_SUMMARY_CHARS
+      ? redacted
+      : `${redacted.slice(0, MAX_SUMMARY_CHARS - 3).trim()}...`;
+  return {
+    agent: {
+      provider: identity.provider,
+      model: identity.model,
+    },
+    task: {
+      domain: inferDomain(summary),
+      summary,
+      constraints: inferConstraints(summary),
+    },
+    ...(clientContext ? { client_context: clientContext } : {}),
+    economics_context: buildEconomicsContext(summary, env, identity),
+    limit: limitFromEnv(env),
+  };
+}
+
+export function buildEconomicsContext(summary, env, identity) {
+  const observedModel = stringOrNull(
+    env.REMEMBRANCE_OBSERVED_MODEL_REVISION ?? env.REMEMBRANCE_MODEL_REVISION,
+  );
+  const requestedModel = stringOrNull(
+    env.REMEMBRANCE_REQUESTED_MODEL ?? identity?.model,
+  );
+  return {
+    runtime: runtimeFromIdentity(identity),
+    ...(stringOrNull(env.REMEMBRANCE_RUNTIME_VERSION)
+      ? { runtime_version: safeText(env.REMEMBRANCE_RUNTIME_VERSION, 120) }
+      : {}),
+    ...(requestedModel
+      ? { requested_model: safeText(requestedModel, 160) }
+      : {}),
+    ...(observedModel
+      ? { observed_model_revision: safeText(observedModel, 160) }
+      : {}),
+    reasoning_effort: normalizeReasoningEffort(
+      env.REMEMBRANCE_REASONING_EFFORT,
+    ),
+    task_stage: inferTaskStage(summary),
+    complexity: inferTaskComplexity(summary),
+    scope: {},
+    measurement_capabilities: ["latency"],
+  };
+}
+
+function inferTaskStage(summary) {
+  if (/\b(review|audit|inspect)\b/i.test(summary)) return "review";
+  if (/\b(test|verify|e2e|qa)\b/i.test(summary)) return "testing";
+  if (/\b(deploy|release|publish|rollout)\b/i.test(summary))
+    return "deployment";
+  if (/\b(debug|fix|failure|error|broken)\b/i.test(summary)) return "debugging";
+  if (/\b(plan|design|architect|approach)\b/i.test(summary)) return "planning";
+  if (/\b(research|evaluate|compare|investigate)\b/i.test(summary))
+    return "research";
+  if (/\b(build|implement|add|create|update|change)\b/i.test(summary)) {
+    return "implementation";
+  }
+  return "unknown";
+}
+
+function inferTaskComplexity(summary) {
+  const text = String(summary ?? "");
+  if (
+    /\b(full|complete|end[- ]to[- ]end|architecture|migration|security)\b/i.test(
+      text,
+    )
+  ) {
+    return "high";
+  }
+  if (text.length > 400 || inferConstraints(text).length >= 2) return "medium";
+  return "unknown";
+}
+
+// Map a prompt to a seeded registry domain so the auto-query is filtered to the
+// right area instead of falling back to a generic catch-all (which surfaces the
+// entry skills regardless of task). Seeded domains: agent-skills, web-ui-qa,
+// resource-discovery, agent-commerce, mcp, mpp. Order matters — most specific
+// first. The web-ui vocabulary is intentionally broad (frontend / dashboard /
+// design work rarely says the words "web ui" or "accessibility").
+export function inferDomain(prompt) {
+  if (/\b(mpp|x402)\b/i.test(prompt)) {
+    return "mpp";
+  }
+  if (
+    /\b(payment|stripe|checkout|billing|invoice|commerce|receipt)\b/i.test(
+      prompt,
+    )
+  ) {
+    return "agent-commerce";
+  }
+  if (
+    /\b(web ?ui|ux|usability|accessibility|a11y|responsive|playwright|frontend|front-end|dashboard|admin (page|panel|surface)|layout|nav(igation| bar| panel)?|sidebar|css|tailwind|styling|component|modal|tooltip|popover|button|form design|redesign|declutter|design system)\b/i.test(
+      prompt,
+    )
+  ) {
+    return "web-ui-qa";
+  }
+  if (
+    /\b(vercel|heroku|deploy|deployment|ci\/cd|github actions?|pipeline|rollback)\b/i.test(
+      prompt,
+    )
+  ) {
+    return "deployment";
+  }
+  if (/\b(mongodb|atlas|redis|database|postgres|sql)\b/i.test(prompt)) {
+    return "database";
+  }
+  if (/\b(mcp|model context protocol|tool server)\b/i.test(prompt)) {
+    return "mcp";
+  }
+  if (
+    /\b(skill|registry|review queue|reviewer|verifier|remembranc\w*|agent memory|skill idea|suggestion)\b/i.test(
+      prompt,
+    )
+  ) {
+    return "agent-skills";
+  }
+  if (
+    /\b(api|endpoint|rest|graphql|webhook|resource|integration|integrate|sdk|service|connector|provider|dataset|docs site)\b/i.test(
+      prompt,
+    )
+  ) {
+    return "resource-discovery";
+  }
+  // No seeded domain fits; agent-skills is the safest default (its entry skill
+  // covers the query/submit workflow itself) rather than a non-existent domain.
+  return "agent-skills";
+}
+
+export function inferConstraints(prompt) {
+  const constraints = [];
+  for (const [pattern, value] of [
+    [/\b(mcp|model context protocol|tool server)\b/i, "mcp"],
+    [/\b(install|setup|set up|configure)\b/i, "setup"],
+    [
+      /\b(api key|enterprise key|organization key|credential)\b/i,
+      "api-key",
+    ],
+    [/\b(troubleshoot|troubleshooting)\b/i, "troubleshooting"],
+    [/\b(ci|github actions?|circleci)\b/i, "ci"],
+    [/\b(deploy|deployment|vercel|heroku)\b/i, "deployment"],
+    [/\b(payment|stripe|mpp|x402)\b/i, "payment"],
+    [/\b(migration|migrate|schema)\b/i, "migration"],
+    [/\b(playwright|browser|responsive|accessibility|a11y)\b/i, "qa"],
+    [
+      /\b(frontend|front-end|dashboard|ux|css|tailwind|react|next\.?js|component|layout|nav|redesign|declutter)\b/i,
+      "frontend",
+    ],
+  ]) {
+    if (pattern.test(prompt)) {
+      constraints.push(value);
+    }
+  }
+  return [...new Set(constraints)];
+}
+
+// --- Query (fetch + timeout, fail-open) --------------------------------------
+
+// Query Remembrance. Returns { body } on success, null on any failure (HTTP
+// error, timeout, malformed JSON, thrown error). Never throws.
+export async function queryRemembrance(payload, options = {}) {
+  const env = options.env ?? process.env;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), autoQueryTimeoutMs(env));
+  try {
+    const credential = resolveApiCredential(env);
+    if (isUnusableConfigurationSource(credential.source)) {
+      debugLog(env, "shared_config_unusable", {}, options);
+      return null;
+    }
+    const headers = {
+      "content-type": "application/json",
+      "user-agent": options.userAgent ?? DEFAULT_USER_AGENT,
+    };
+    const apiKey = credential.apiKey;
+    if (apiKey) {
+      headers["x-remembrance-api-key"] = apiKey;
+    }
+    const response = await fetchImpl(`${apiUrl(env)}/api/v1/agent/query`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      debugLog(
+        env,
+        "http_error",
+        { status: response.status, api_url: apiUrl(env) },
+        options,
+      );
+      return null;
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch (error) {
+      debugLog(env, "malformed_response", { error: errorName(error) }, options);
+      return null;
+    }
+    return { body };
+  } catch (error) {
+    debugLog(
+      env,
+      errorName(error) === "AbortError" ? "timeout" : "request_error",
+      { error: errorName(error) },
+      options,
+    );
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function createContinuationDirective(options = {}) {
+  const directive = {
+    directive_id: `dir_${randomBytes(16).toString("hex")}`,
+    runtime: normalizeRuntime(options.runtime),
+    trigger_reason: safeText(
+      options.triggerReason ?? "contextual_continuation",
+      160,
+    ),
+    shown_at: new Date().toISOString(),
+  };
+  if (options.reportShown !== false) {
+    await reportDirectiveEvent(
+      {
+        event: "shown",
+        directive_id: directive.directive_id,
+        surface: "plugin_hook",
+        runtime: directive.runtime,
+        trigger_reason: directive.trigger_reason,
+      },
+      options,
+    );
+  }
+  return directive;
+}
+
+// Directive telemetry is deliberately fail-open and analytics-only. Hooks wait
+// briefly for the shown event so a fast subsequent MCP query cannot overtake
+// its denominator record, but an unavailable registry never blocks the prompt.
+export async function reportDirectiveEvent(event, options = {}) {
+  const env = options.env ?? process.env;
+  const fetchImpl = options.fetchImpl ?? fetch;
+  const controller = new AbortController();
+  const timeout = setTimeout(
+    () => controller.abort(),
+    directiveEventTimeoutMs(env),
+  );
+  try {
+    const credential = resolveApiCredential(env);
+    if (isUnusableConfigurationSource(credential.source)) return false;
+    const headers = {
+      "content-type": "application/json",
+      "user-agent": options.userAgent ?? DEFAULT_USER_AGENT,
+    };
+    const apiKey = credential.apiKey;
+    if (apiKey) headers["x-remembrance-api-key"] = apiKey;
+    const response = await fetchImpl(
+      `${apiUrl(env)}/api/v1/agent/directive-events`,
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify(event),
+        signal: controller.signal,
+      },
+    );
+    if (!response?.ok) {
+      debugLog(
+        env,
+        "directive_event_http_error",
+        { status: response?.status ?? "unavailable" },
+        options,
+      );
+      return false;
+    }
+    return true;
+  } catch (error) {
+    debugLog(
+      env,
+      "directive_event_error",
+      { error: errorName(error) },
+      options,
+    );
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function runtimeFromIdentity(identity) {
+  return normalizeRuntime(identity?.provider ?? "codex");
+}
+
+function normalizeRuntime(value) {
+  if (value === "claude") return "claude_code";
+  if (value === "vscode") return "vs_code";
+  if (
+    [
+      "codex",
+      "claude_code",
+      "cursor",
+      "openclaw",
+      "vs_code",
+      "opencode",
+      "other",
+    ].includes(value)
+  ) {
+    return value;
+  }
+  return "unknown";
+}
+
+// --- Context formatting ------------------------------------------------------
+
+function publicSkillCandidateAllowed(body, candidate) {
+  return (
+    body?.skill_access?.public_skills_allowed !== false ||
+    candidate?.source === "org_overlay"
+  );
+}
+
+export function highMatchFromResponse(response) {
+  const body = responseBodyFromToolResponse(response);
+  const queryId = body?.query_feedback?.query_id ?? body?.query_id ?? null;
+  const candidates = [
+    ...(Array.isArray(body?.skills)
+      ? body.skills
+          .filter((item) => publicSkillCandidateAllowed(body, item))
+          .map((item) => ({ ...item, target_type: "skill" }))
+      : []),
+    ...(Array.isArray(body?.resources)
+      ? body.resources.map((item) => ({ ...item, target_type: "resource" }))
+      : []),
+  ];
+  const candidate = candidates.find((item) => item?.match_tier === "high");
+  if (!candidate?.slug) return null;
+  return {
+    query_id: queryId ? safeText(queryId, 80) : null,
+    result_id: candidate.result_id ? safeText(candidate.result_id, 80) : null,
+    target_type: candidate.target_type,
+    slug: safeText(candidate.slug, 120),
+    match_reason: safeText(
+      candidate.match_reason ?? "Strong task coverage",
+      160,
+    ),
+    estimated_tokens: Number.isFinite(candidate.estimated_tokens)
+      ? Math.max(0, Math.round(candidate.estimated_tokens))
+      : null,
+    verified_uses: numberValue(candidate.verified_uses),
+    risk_level: safeText(candidate.risk_level ?? "unknown", 24),
+    why_matched: sanitizeWhyMatched(candidate.why_matched),
+    applicability: sanitizeApplicability(candidate.applicability),
+    value_estimate_id: candidate.value_estimate_id
+      ? safeText(candidate.value_estimate_id, 80)
+      : null,
+    potential_savings: sanitizePotentialSavings(candidate.potential_savings),
+  };
+}
+
+// Format the query response into the plain context string Codex injects via
+// additionalContext. Returns null when there is nothing useful to inject.
+export function formatContext(
+  response,
+  reason = "trigger_match",
+  limit = DEFAULT_LIMIT,
+) {
+  const body = responseBodyFromToolResponse(response);
+  const itemLimit = Math.min(Math.max(Number(limit) || DEFAULT_LIMIT, 1), 10);
+  const skills = Array.isArray(body?.skills)
+    ? body.skills
+        .filter((item) => publicSkillCandidateAllowed(body, item))
+        .slice(0, itemLimit)
+    : [];
+  const resources = Array.isArray(body?.resources)
+    ? body.resources.slice(0, itemLimit)
+    : [];
+  const noResults = body?.no_results ?? null;
+  if (skills.length === 0 && resources.length === 0 && !noResults) {
+    return null;
+  }
+
+  const lines = [
+    "Remembrance auto-query context:",
+    `Trigger: ${reason}. Use these results only if they fit the user's task constraints.`,
+  ];
+  if (body?.skill_access?.policy === "org_only") {
+    lines.push(
+      "Organization policy: use organization skills only. Do not use public skills or bundled public skill references, including as an offline fallback.",
+    );
+  }
+  const queryId = body?.query_feedback?.query_id ?? body?.query_id;
+  const highMatch = highMatchFromResponse(body);
+  if (queryId) {
+    lines.push(
+      `Query receipt: ${safeText(queryId, 80)}. Use this query_id with the result IDs below when calling submit_query_feedback.`,
+    );
+  }
+  if (highMatch) {
+    const tool =
+      highMatch.target_type === "resource" ? "get_resource" : "get_skill";
+    const args = {
+      slug: highMatch.slug,
+      ...(highMatch.query_id ? { query_id: highMatch.query_id } : {}),
+      ...(highMatch.result_id ? { result_id: highMatch.result_id } : {}),
+    };
+    lines.push(
+      `HIGH MATCH — required next step: call ${tool} with ${JSON.stringify(args)} before proceeding. ${highMatch.match_reason}; ${matchEvidenceLabel(highMatch)}. If it does not actually fit, do not force its use: submit query feedback with fit poor and a concrete reason.`,
+    );
+  }
+  // Tail lines (the no-results payload, the contribution directive, and the
+  // delegation instruction) are the actionable part of this context. They are
+  // reserved BEFORE candidate lines fill the remaining budget — the previous
+  // append-then-truncate order let rich per-candidate decision labels push
+  // them past MAX_CONTEXT_CHARS, silently evicting the directive.
+  const tailLines = [];
+  if (noResults) {
+    const payload = safeText(
+      JSON.stringify(noResults.propose_skill_idea_payload ?? noResults),
+      1200,
+    );
+    tailLines.push(
+      `No matching skill/resource. Proposed skill idea payload: ${payload}`,
+    );
+  }
+  const contributionDirective =
+    body?.contribution_directive?.message ?? body?.fallback_instruction;
+  if (contributionDirective) {
+    tailLines.push(
+      `After using Remembrance: ${safeText(contributionDirective, MAX_DIRECTIVE_CHARS)}`,
+    );
+  }
+  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.",
+    );
+  }
+
+  const candidateSections = [];
+  if (skills.length > 0) {
+    candidateSections.push({
+      header: "Skills:",
+      lines: skills.map(
+        (skill) =>
+          `- [${matchTierLabel(skill.match_tier)}] ${safeText(skill.slug, 80)} (${candidateEvidenceLabel(skill)}${skill.result_id ? `, result ${safeText(skill.result_id, 80)}` : ""}): ${safeText(skill.description, MAX_CONTEXT_FIELD_CHARS)}${candidateDecisionLabel(skill)}`,
+      ),
+    });
+  }
+  if (resources.length > 0) {
+    candidateSections.push({
+      header: "Resources:",
+      lines: resources.map(
+        (resource) =>
+          `- [${matchTierLabel(resource.match_tier)}] ${safeText(resource.slug, 80)} [${safeText(resource.kind, 40)}, ${candidateEvidenceLabel(resource)}${resource.result_id ? `, result ${safeText(resource.result_id, 80)}` : ""}]: ${safeText(resource.description, MAX_CONTEXT_FIELD_CHARS)}${candidateDecisionLabel(resource)}`,
+      ),
+    });
+  }
+  lines.push(
+    ...budgetedCandidateLines(
+      candidateSections,
+      MAX_CONTEXT_CHARS - joinedLength([...lines, ...tailLines]),
+    ),
+  );
+  lines.push(...tailLines);
+  return safeText(lines.join("\n"), MAX_CONTEXT_CHARS);
+}
+
+function joinedLength(lines) {
+  return lines.reduce(
+    (total, line) => total + line.length,
+    Math.max(0, lines.length - 1),
+  );
+}
+
+// Fit candidate lines (with their section headers) into the character budget
+// left after the head/tail lines. Dropping is explicit, never silent: when
+// candidates are omitted, a short note says how many and gives the agent the
+// explicit recovery action.
+function budgetedCandidateLines(sections, budget) {
+  const total = sections.reduce(
+    (count, section) => count + section.lines.length,
+    0,
+  );
+  const omissionNote = (count) =>
+    `(+${count} more match${count === 1 ? "" : "es"} omitted to fit this context; call query_skills with the current task context to retrieve the full list.)`;
+  // +1: inserting this block between head and tail costs one MORE newline
+  // than the block's own internal joins (joinedLength counts n-1 separators
+  // for n lines; the block itself joins to its neighbors with an nth).
+  const fits = (lines) => joinedLength(lines) + 1 <= budget;
+
+  const chosen = [];
+  let shown = 0;
+  for (const section of sections) {
+    let headerAdded = false;
+    for (const line of section.lines) {
+      const attempt = headerAdded
+        ? [...chosen, line]
+        : [...chosen, section.header, line];
+      const remainingAfter = total - (shown + 1);
+      // Every non-final line must leave room for the omission note, so that
+      // if the NEXT line does not fit, the note (for exactly that many
+      // dropped candidates) is guaranteed to fit alongside what was kept.
+      const accepted =
+        remainingAfter > 0
+          ? fits([...attempt, omissionNote(remainingAfter)])
+          : fits(attempt);
+      if (!accepted) {
+        const dropped = total - shown;
+        if (fits([...chosen, omissionNote(dropped)])) {
+          chosen.push(omissionNote(dropped));
+        }
+        return chosen;
+      }
+      chosen.length = 0;
+      chosen.push(...attempt);
+      headerAdded = true;
+      shown += 1;
+    }
+  }
+  return chosen;
+}
+
+function matchTierLabel(value) {
+  if (value === "high") return "HIGH MATCH";
+  if (value === "possible") return "POSSIBLE MATCH";
+  return "EXPLORATORY";
+}
+
+function candidateEvidenceLabel(candidate) {
+  const tokens = Number.isFinite(candidate?.estimated_tokens)
+    ? `~${Math.max(0, Math.round(candidate.estimated_tokens))} tokens`
+    : "size unknown";
+  const verified = numberValue(candidate?.verified_uses);
+  const savings = potentialSavingsLabel(candidate?.potential_savings);
+  return `${tokens}, ${verified} verified ${verified === 1 ? "use" : "uses"}, risk ${safeText(candidate?.risk_level ?? "unknown", 24)}${savings ? `, ${savings}` : ""}`;
+}
+
+function candidateDecisionLabel(candidate) {
+  const why = sanitizeWhyMatched(candidate?.why_matched);
+  const applicability = sanitizeApplicability(candidate?.applicability);
+  const evidence = [];
+  if (why?.matched_terms.length) {
+    evidence.push(`terms ${why.matched_terms.join(", ")}`);
+  }
+  if (why?.matched_capabilities.length) {
+    evidence.push(`capabilities ${why.matched_capabilities.join(", ")}`);
+  }
+  if (why?.domain_match) evidence.push("exact domain");
+  if (why?.satisfied_constraints.length) {
+    evidence.push(`constraints met ${why.satisfied_constraints.join(", ")}`);
+  }
+  if (why?.missed_constraints.length) {
+    evidence.push(`constraints missing ${why.missed_constraints.join(", ")}`);
+  }
+  if (why) {
+    evidence.push(
+      `signals lexical ${why.lexical_signal}, semantic ${why.semantic_signal}`,
+    );
+  }
+
+  const applicabilityParts = [];
+  if (applicability) {
+    applicabilityParts.push(
+      `applicability ${applicability.fit}/${applicability.scope}: ${applicability.reason}`,
+    );
+    if (applicability.use_when.length) {
+      applicabilityParts.push(
+        `use only when ${applicability.use_when.join("; ")}`,
+      );
+    }
+    if (applicability.avoid_when.length) {
+      applicabilityParts.push(
+        `avoid when ${applicability.avoid_when.join("; ")}`,
+      );
+    }
+  }
+  const details = [...evidence, ...applicabilityParts];
+  return details.length > 0
+    ? ` Decision: ${safeText(details.join("; "), 640)}.`
+    : "";
+}
+
+function sanitizeWhyMatched(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  return {
+    matched_terms: safeStringList(value.matched_terms, 4, 48),
+    matched_capabilities: safeStringList(value.matched_capabilities, 3, 80),
+    domain_match: value.domain_match === true,
+    satisfied_constraints: safeStringList(value.satisfied_constraints, 3, 100),
+    missed_constraints: safeStringList(value.missed_constraints, 3, 100),
+    lexical_signal: signalStrength(value.lexical_signal),
+    semantic_signal: signalStrength(value.semantic_signal),
+  };
+}
+
+function sanitizeApplicability(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const fit = ["likely", "conditional", "unlikely", "unknown"].includes(
+    value.fit,
+  )
+    ? value.fit
+    : "unknown";
+  const scope = ["general", "specialized", "corner_case", "unknown"].includes(
+    value.scope,
+  )
+    ? value.scope
+    : "unknown";
+  return {
+    fit,
+    scope,
+    reason: safeText(value.reason ?? "No applicability reason provided", 180),
+    use_when: safeStringList(value.use_when, 2, 120),
+    avoid_when: safeStringList(value.avoid_when, 2, 120),
+  };
+}
+
+function safeStringList(value, limit, maxChars) {
+  if (!Array.isArray(value)) return [];
+  return [
+    ...new Set(
+      value
+        .filter((item) => typeof item === "string" && item.trim())
+        .map((item) => safeText(item, maxChars)),
+    ),
+  ].slice(0, limit);
+}
+
+function signalStrength(value) {
+  return ["none", "weak", "moderate", "strong"].includes(value)
+    ? value
+    : "none";
+}
+
+function matchEvidenceLabel(match) {
+  const tokens = Number.isFinite(match.estimated_tokens)
+    ? `~${match.estimated_tokens} tokens`
+    : "size unknown";
+  const savings = potentialSavingsLabel(match.potential_savings);
+  return `${tokens}, ${match.verified_uses} verified ${match.verified_uses === 1 ? "use" : "uses"}, risk ${match.risk_level}${savings ? `, ${savings}` : ""}${candidateDecisionLabel(match)}`;
+}
+
+export function continuationQueryContext(directive = null) {
+  const clientContext = directive
+    ? ` Use client_context ${JSON.stringify({
+        runtime: directive.runtime,
+        trigger_reason: directive.trigger_reason,
+        directive_id: directive.directive_id,
+      })} so Remembrance can measure whether this instruction was followed.`
+    : "";
+  return [
+    "Remembrance task-continuation reminder:",
+    `This prompt depends on earlier conversation. Infer the concrete task, domain, and constraints from the full thread, then call the Remembrance MCP tool query_skills before acting; do not wait for the current prompt to repeat service, framework, workflow, or UI keywords.${clientContext}`,
+    "If MCP is unavailable, use POST /api/v1/agent/query. Do not send raw prior conversation: submit a redacted task summary and constraints.",
+    "Before finishing, use submit_query_feedback once with one complete set of explicit good/partial/poor query matches, submit_feedback and submit_remembrance when a returned skill was actually used, or submit a failure_report / skill idea only when a reusable lesson or genuinely missing workflow was found.",
+  ].join("\n");
+}
+
+export function unavailableQueryContext(env = process.env) {
+  const credential = resolveApiCredential(env);
+  const organizationFallback = isUnusableConfigurationSource(credential.source)
+    ? "The shared Remembrance config exists but is unreadable or invalid. Fail closed: do not use bundled public references or remote tools until the config is fixed or intentionally removed."
+    : credential.apiKey
+      ? "An organization API key is configured, but the organization skill policy could not be confirmed. Fail closed: do not use bundled public skill references while the query is unavailable."
+      : "No organization API key is configured; bundled public references remain an optional offline fallback.";
+  return [
+    "Remembrance query-unavailable context:",
+    "This task qualified for Remembrance, but the automatic query did not complete. Continue without blocking, and call query_skills directly when the MCP tool is visible.",
+    organizationFallback,
+    "Before finishing, submit a failure_report only if the outage or workaround produced a reusable lesson. Redact secrets, private URLs, credentials, and proprietary content.",
+  ].join("\n");
+}
+
+export function emptyQueryContext(reason = "trigger_match") {
+  return [
+    "Remembrance auto-query context:",
+    `Trigger: ${reason}. The query completed but returned no matching skill or resource.`,
+    "Use the full conversation before deciding whether the workflow is genuinely missing. Propose a skill idea only when you built a reusable workflow that the registry does not already cover.",
+    "Before finishing, submit a failure_report when the task exposed a reusable failure lesson.",
+  ].join("\n");
+}
+
+// --- High-level query orchestration ------------------------------------------
+
+// Full prompt-hook result. `eligible` means this turn should be recovered at
+// completion even if no registry result was consumed. `consumed` means a real
+// query completed; `matched` means that response contained at least one result
+// the current credential is allowed to use.
+export async function runPromptHook(prompt, options = {}) {
+  const env = options.env ?? process.env;
+  const includeSharedConfigCredentialNotice =
+    options.includeSharedConfigCredentialNotice !== false;
+  if (disabled(env.REMEMBRANCE_AUTO_QUERY)) {
+    debugLog(env, "disabled", {}, options);
+    return null;
+  }
+  const redacted = redactPrompt(String(prompt ?? ""));
+  const decision = shouldQueryPrompt(redacted);
+  if (!decision.likely_match) {
+    if (isContextualContinuationPrompt(redacted)) {
+      const directive = await createContinuationDirective({
+        env,
+        fetchImpl: options.fetchImpl ?? fetch,
+        reportShown: options.reportDirectiveShown,
+        runtime: runtimeFromIdentity(options.identity),
+        stderr: options.stderr,
+        userAgent: options.userAgent,
+      });
+      return {
+        consumed: false,
+        context: continuationQueryContext(directive),
+        directive,
+        eligible: true,
+        reason: "contextual_continuation",
+      };
+    }
+    debugLog(env, "skip", { reason: decision.reason }, options);
+    return null;
+  }
+  const payload = buildQueryPayload(redacted, env, options.identity, {
+    surface: "plugin_hook",
+    runtime: runtimeFromIdentity(options.identity),
+    trigger_reason: decision.reason,
+  });
+  const response = await queryRemembrance(payload, {
+    env,
+    fetchImpl: options.fetchImpl ?? fetch,
+    stderr: options.stderr,
+    userAgent: options.userAgent,
+  });
+  if (!response) {
+    return {
+      consumed: false,
+      context: includeSharedConfigCredentialNotice
+        ? withSharedConfigCredentialNotice(unavailableQueryContext(env), env)
+        : unavailableQueryContext(env),
+      eligible: true,
+      reason: "query_unavailable",
+    };
+  }
+  return {
+    consumed: true,
+    matched: queryResponseHasMatches(response),
+    context: includeSharedConfigCredentialNotice
+      ? withSharedConfigCredentialNotice(
+          formatContext(response, decision.reason, limitFromEnv(env)) ??
+            emptyQueryContext(decision.reason),
+          env,
+        )
+      : (formatContext(response, decision.reason, limitFromEnv(env)) ??
+        emptyQueryContext(decision.reason)),
+    eligible: true,
+    highMatch: highMatchFromResponse(response),
+    valueEpisode: valueEpisodeFromResponse(response),
+    reason: decision.reason,
+  };
+}
+
+export function queryResponseHasMatches(response) {
+  const body = responseBodyFromToolResponse(response);
+  const skills = Array.isArray(body?.skills)
+    ? body.skills.filter((item) => publicSkillCandidateAllowed(body, item))
+    : [];
+  const resources = Array.isArray(body?.resources) ? body.resources : [];
+  return skills.length > 0 || resources.length > 0;
+}
+
+function withSharedConfigCredentialNotice(context, env) {
+  const notice = sharedConfigCredentialNotice(env);
+  return notice ? `${notice}\n\n${context}` : context;
+}
+
+// Backward-compatible string-only wrapper used by callers that do not need the
+// eligibility/consumption distinction.
+export async function runQuery(prompt, options = {}) {
+  return (await runPromptHook(prompt, options))?.context ?? null;
+}
+
+// --- Contribution decision (stop hook) ---------------------------------------
+
+// Count only CONSUMPTION of the registry (queries / explicit skill retrieval) —
+// not the agent's own submissions. Kept for parity with the Claude hook and for
+// any transcript-shaped input a caller wants to scan; Codex's own Stop payload
+// has no transcript, so the marker mechanism below is what actually drives the
+// Codex stop decision.
+const CONSUMPTION_MARKERS =
+  /Remembrance auto-query context|mcp__[a-z0-9_]*remembrance[a-z0-9_]*__(query_skills|get_skill|get_resource|invoke_skill)|\/api\/v1\/agent\/(?:query(?!-feedback)|skill-invocations)\b/gi;
+
+const TASK_ELIGIBILITY_MARKERS =
+  /Remembrance task-continuation reminder|Remembrance query-unavailable context/gi;
+
+const CONTRIBUTION_SUBMITTED_PATTERNS = [
+  /\brpub_[a-f0-9]{16,}\b/i,
+  /\bsubmitted (?:it|this|the lesson|the failure|the remembrance) (?:to|as) Remembrance\b/i,
+  /\bsubmit_remembrance\b/i,
+  /\bREMEMBRANCE_SUBMISSION_PAYLOAD\b/,
+];
+
+const HIGH_VALUE_LESSON_PATTERNS = [
+  {
+    pattern:
+      /\b(?:missed|missing|forgot(?:ten)?)\b.{0,80}\b(?:version bump|package version|plugin version|mcp package version)\b/i,
+    reason: "release versioning miss",
+  },
+  {
+    pattern:
+      /\b(?:publish-impacting|check:mcp-package-version|sync:versions|refresh:generated)\b/i,
+    reason: "publish or generated-artifact release lesson",
+  },
+  {
+    pattern:
+      /\b(?:regression|circleci failed|ci failed|deployment failed|deploy failed)\b/i,
+    reason: "failure or regression",
+  },
+  {
+    pattern:
+      /\bI (?:missed|forgot|overlooked|failed to|should have|should've|did not|didn't)\b/i,
+    reason: "self-correction or missed step",
+  },
+  {
+    pattern: /\b(?:you|the user) (?:caught|pointed out|had to ask)\b/i,
+    reason: "user-caught agent miss",
+  },
+];
+
+export function countRegistryConsumption(transcript) {
+  const matches = String(transcript ?? "").match(CONSUMPTION_MARKERS);
+  return matches ? matches.length : 0;
+}
+
+export function countTaskEligibility(transcript) {
+  const matches = String(transcript ?? "").match(TASK_ELIGIBILITY_MARKERS);
+  return matches ? matches.length : 0;
+}
+
+export function contributionReason(
+  signal = null,
+  highMatch = null,
+  directSelection = null,
+) {
+  const signalLine = signal
+    ? `High-value lesson detected: ${signal}. Capture it unless you already submitted the lesson.`
+    : null;
+  const highMatchLine = highMatch
+    ? highMatchClosureInstruction(highMatch)
+    : null;
+  const directSelections = (
+    Array.isArray(directSelection)
+      ? directSelection
+      : directSelection
+        ? [directSelection]
+        : []
+  ).slice(0, DIRECT_SELECTION_MARKER_LIMIT);
+  if (directSelections.length > 0) {
+    const selectionLines = directSelections.map((selection) => {
+      const correlation =
+        selection.query_id && selection.result_id
+          ? ` Use query_id ${selection.query_id} and result_id ${selection.result_id}.`
+          : "";
+      return `- ${selection.slug}${selection.version ? ` version ${selection.version}` : ""}.${correlation}`;
+    });
+    return [
+      directSelections.length === 1
+        ? `Before you finish: you explicitly used this Remembrance skill:`
+        : `Before you finish: you explicitly used ${directSelections.length} Remembrance skills:`,
+      ...selectionLines,
+      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.",
+      "If submit_feedback returns next_step.submit_remembrance_payload, submit that reviewed evidence when the lesson is reusable.",
+      "Report failed attempts, corrections, security findings, and reusable workflow improvements instead of silently changing the skill.",
+      "If host privacy policy blocks private repository-derived instructions, do not retry through another transport: queue organization skills locally with queue_private_skill_import (or the bundled handoff script) and wait for an admin import receipt.",
+      "Redact secrets, private URLs, credentials, prompts, outputs, source paths, and proprietary content.",
+      "If nothing is genuinely worth capturing, say so in one line; you will not be asked again for this use.",
+    ]
+      .filter(Boolean)
+      .join("\n");
+  }
+  return [
+    "Before you finish: you used Remembrance this session.",
+    signalLine,
+    highMatchLine,
+    "If you learned something reusable — a lesson, a gotcha, a fix, a skill that helped, or a skill that was missing — contribute it now so the next agent inherits it instead of rediscovering it:",
+    "• submit_query_feedback — send one complete good / partial / poor verdict set using query_id and returned result_id values; leave uncertain results unrated. A poor query match is not the same as a globally bad skill.",
+    "• submit_feedback — a quick useful / not-useful signal plus a one-line lesson.",
+    "• submit_remembrance — post the ready next_step.submit_remembrance_payload returned by submit_feedback when the lesson is reusable, adding redacted evidence when available.",
+    "• propose_private_skill — the default proposal path. Use it for anything repository-derived or organization-specific, after the host and organization approve Remembrance as the destination. It cannot create a public candidate under any credential state, so it stays private even if your key stops resolving.",
+    "• propose_skill_idea — only if no existing skill fit, you built a reusable workflow, AND a public candidate is an acceptable outcome. An active organization key keeps it private; intentionally omitting a key makes the call PUBLIC. A supplied invalid/inactive key fails with 401 and an insufficient key fails with 403, creating no candidate. Read `visibility` in a successful response (organization_private or public_candidate) and report where it landed. Never remove or bypass the key to force a public candidate.",
+    "Use the Remembrance MCP tools directly when they are visible. If this runtime has no MCP tools exposed, use the REST endpoints from the query response. A host privacy-policy denial is not API unavailability: never retry private repository content through another transport; queue organization skills locally with queue_private_skill_import (or the bundled handoff script) and wait for an admin import receipt. If the API itself is unavailable, emit REMEMBRANCE_SUBMISSION_PAYLOAD with the redacted JSON you would submit.",
+    "Redact secrets, private URLs, and proprietary content; submit redacted summaries and hashes, not raw traces.",
+    "Attach evidence: reproduction detail in outcome.failure_modes, artifact hashes of redacted logs/diffs, or an attestation. Evidence-less public reports wait in unverified intake until corroborated; evidence-backed ones verify faster and rank higher.",
+    "If nothing is genuinely worth capturing, just say so in one line — you will not be asked again this session.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function taskClosureReason(signal = null) {
+  const signalLine = signal
+    ? `High-value lesson detected: ${signal}. Capture it unless you already submitted the lesson.`
+    : null;
+  return [
+    "Before you finish: this session involved a reusable service, API, tool, workflow, UI, review, or engineering task, but no completed Remembrance query/use was recorded.",
+    signalLine,
+    "Infer the concrete task from the full conversation and call query_skills now when the MCP tool is visible. If MCP is unavailable, use POST /api/v1/agent/query with a redacted summary.",
+    "Evaluate returned result IDs explicitly: call submit_query_feedback once with the complete good/partial/poor verdict set, then use submit_feedback only after actually using a skill. If nothing fits, report overall_fit none and propose a skill idea only when you actually built a reusable workflow.",
+    "Submit a failure_report for a reusable self-correction, user-caught mistake, CI/deploy failure, security issue, or release/versioning miss even when no skill was used.",
+    "Redact secrets, private URLs, credentials, raw logs, and proprietary content; attach bounded reproduction detail or artifact hashes when available.",
+    "If the task was truly trivial and produced no reusable lesson, say so in one line; you will not be asked again for this task.",
+  ]
+    .filter(Boolean)
+    .join("\n");
+}
+
+export function detectHighValueLessonSignal(input) {
+  return detectHighValueLessonSignalInText(
+    input?.last_assistant_message ??
+      input?.lastAssistantMessage ??
+      input?.assistant_message ??
+      input?.message ??
+      "",
+  );
+}
+
+export function detectHighValueLessonSignalInText(text) {
+  const value = String(text ?? "");
+  if (!value.trim()) {
+    return null;
+  }
+  if (CONTRIBUTION_SUBMITTED_PATTERNS.some((pattern) => pattern.test(value))) {
+    return null;
+  }
+  for (const { pattern, reason } of HIGH_VALUE_LESSON_PATTERNS) {
+    if (pattern.test(value)) {
+      return reason;
+    }
+  }
+  return null;
+}
+
+// Pure decision function (unit-tested): compare completed registry use and task
+// eligibility with the last-prompted count. A completed use prompts for a
+// contribution; eligible work with no completed query prompts for full-context
+// recovery. `useCount`/`promptedCount` are injectable so tests never touch the
+// filesystem.
+export function decideStop(input, options = {}) {
+  const env = options.env ?? process.env;
+  if (contributeDisabled(env.REMEMBRANCE_AUTO_CONTRIBUTE)) {
+    return { allow: true, why: "disabled" };
+  }
+  if (input?.stop_hook_active) {
+    return { allow: true, why: "stop_hook_active" };
+  }
+  const sessionId = sessionIdFor(input);
+  const readUse = options.readUseCount ?? readRegistryUseCount;
+  const useCount = readUse(sessionId, env);
+  const readEligible = options.readEligibilityCount ?? readTaskEligibilityCount;
+  const eligibilityCount = readEligible(sessionId, env);
+  const engagementCount = Math.max(useCount, eligibilityCount);
+  const readPrompted = options.readPromptedCount ?? readPromptedCount;
+  const promptedCount = readPrompted(sessionId, env);
+  const readHighMatch = options.readHighMatch ?? readHighMatchSurface;
+  const highMatch = readHighMatch(sessionId, env);
+  const directSelections = options.readDirectSelections
+    ? options.readDirectSelections(sessionId, env)
+    : options.readDirectSelection
+      ? [options.readDirectSelection(sessionId, env)].filter(Boolean)
+      : readDirectSelectionSurfaces(sessionId, env);
+  const newDirectSelections = directSelections.filter(
+    (selection) => !selection?.prompted_at,
+  );
+  const feedbackDirectSelections = newDirectSelections.filter(
+    (selection) => selection.feedback_available !== false,
+  );
+  const hasUnclosedEligibility =
+    eligibilityCount > useCount && newDirectSelections.length === 0;
+  const highValueSignal = detectHighValueLessonSignal(input);
+  if (newDirectSelections.length > 0 && feedbackDirectSelections.length === 0) {
+    return { allow: true, why: "direct_feedback_unavailable" };
+  }
+  if (engagementCount === 0 && !highValueSignal) {
+    return { allow: true, why: "registry_not_used" };
+  }
+  if (
+    engagementCount <= promptedCount &&
+    newDirectSelections.length === 0 &&
+    !highValueSignal
+  ) {
+    return { allow: true, why: "no_new_usage" };
+  }
+  if (
+    highValueSignal &&
+    promptedCount > 0 &&
+    engagementCount <= promptedCount
+  ) {
+    return { allow: true, why: "high_value_lesson_already_prompted" };
+  }
+  return {
+    allow: false,
+    why: highValueSignal
+      ? "prompt_high_value_lesson_contribution"
+      : hasUnclosedEligibility
+        ? "prompt_task_closure"
+        : "prompt_contribution",
+    reason: hasUnclosedEligibility
+      ? taskClosureReason(highValueSignal)
+      : contributionReason(
+          highValueSignal,
+          highMatch,
+          feedbackDirectSelections.length > 0 ? feedbackDirectSelections : null,
+        ),
+    useCount: highValueSignal
+      ? Math.max(engagementCount, promptedCount + 1, 1)
+      : engagementCount,
+  };
+}
+
+function highMatchClosureInstruction(match) {
+  const tool = match.target_type === "resource" ? "get_resource" : "get_skill";
+  const args = {
+    slug: safeText(match.slug, 120),
+    ...(match.query_id ? { query_id: safeText(match.query_id, 80) } : {}),
+    ...(match.result_id ? { result_id: safeText(match.result_id, 80) } : {}),
+  };
+  return `High-confidence result surfaced: ${safeText(match.slug, 120)} (${matchEvidenceLabel(match)}). If you have not opened it, call ${tool} with ${JSON.stringify(args)} now. If it is not a fit, skip it and submit query feedback with fit poor plus the reason; after use, pass the same query_id/result_id to submit_feedback.`;
+}
+
+// --- Marker mechanism (Codex has no transcript path) -------------------------
+//
+// Three per-session counters and one bounded high-match marker live under
+// os.tmpdir()/remembrance-usage/<hash>:
+//   <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.
+//   <hash>.prompt  — the use count at which the stop adapter last prompted.
+//   <hash>.high-match.json — latest high result until its exact detail opens.
+// The stop adapter compares max(.use, .eligible) with .prompt, then records the
+// new engagement count. This reproduces the Claude hook's sentinel behavior
+// without retaining a transcript.
+
+const USAGE_DIR = "remembrance-usage";
+
+function usageDir(env = process.env) {
+  return env?.REMEMBRANCE_USAGE_DIR
+    ? String(env.REMEMBRANCE_USAGE_DIR)
+    : join(tmpdir(), USAGE_DIR);
+}
+
+function sessionHash(sessionId) {
+  return createHash("sha256")
+    .update(String(sessionId ?? "unknown"))
+    .digest("hex")
+    .slice(0, 16);
+}
+
+function usePath(sessionId, env) {
+  return join(usageDir(env), `${sessionHash(sessionId)}.use`);
+}
+
+function promptPath(sessionId, env) {
+  return join(usageDir(env), `${sessionHash(sessionId)}.prompt`);
+}
+
+function eligibilityPath(sessionId, env) {
+  return join(usageDir(env), `${sessionHash(sessionId)}.eligible`);
+}
+
+function highMatchPath(sessionId, env) {
+  return join(usageDir(env), `${sessionHash(sessionId)}.high-match.json`);
+}
+
+function valueEpisodePath(sessionId, env) {
+  return join(usageDir(env), `${sessionHash(sessionId)}.value-episodes.json`);
+}
+
+function directSelectionPath(sessionId, env) {
+  return join(usageDir(env), `${sessionHash(sessionId)}.direct-skill.json`);
+}
+
+function directivePath(sessionId, env) {
+  return join(usageDir(env), `${sessionHash(sessionId)}.directive.json`);
+}
+
+function readCountFile(path) {
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = Number.parseInt(String(raw).trim(), 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : 0;
+  } catch {
+    return 0;
+  }
+}
+
+function writeCountFile(path, count) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, String(count));
+    return true;
+  } catch {
+    // Non-fatal: fail-open, the stop_hook_active guard still prevents loops.
+    return false;
+  }
+}
+
+// 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
+// without inflating registry-use counts. Fail-open on filesystem errors.
+export function recordRegistryUse(sessionId, env = process.env) {
+  const path = usePath(sessionId, env);
+  const next = readCountFile(path) + 1;
+  writeCountFile(path, next);
+  return next;
+}
+
+export function markCurrentEngagementHandled(sessionId, env = process.env) {
+  const count = Math.max(
+    readRegistryUseCount(sessionId, env),
+    readTaskEligibilityCount(sessionId, env),
+  );
+  if (count > 0) {
+    writePromptedCount(sessionId, count, env);
+  }
+  return count;
+}
+
+// Read the per-session registry-use counter (0 if never recorded).
+export function readRegistryUseCount(sessionId, env = process.env) {
+  return readCountFile(usePath(sessionId, env));
+}
+
+// Increment task eligibility for each qualifying prompt. The prompted-count
+// sentinel makes each task recoverable once without re-blocking the Stop retry.
+export function recordTaskEligibility(sessionId, env = process.env) {
+  const path = eligibilityPath(sessionId, env);
+  const next = readCountFile(path) + 1;
+  writeCountFile(path, next);
+  return next;
+}
+
+export function readTaskEligibilityCount(sessionId, env = process.env) {
+  return readCountFile(eligibilityPath(sessionId, env));
+}
+
+export function recordDirectiveSurface(
+  sessionId,
+  directive,
+  env = process.env,
+) {
+  const path = directivePath(sessionId, env);
+  try {
+    if (!directive) {
+      rmSync(path, { force: true });
+      return true;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        directive_id: safeText(directive.directive_id, 96),
+        runtime: normalizeRuntime(directive.runtime),
+        trigger_reason: safeText(
+          directive.trigger_reason ?? "contextual_continuation",
+          160,
+        ),
+        shown_at: safeText(directive.shown_at ?? new Date().toISOString(), 40),
+      }),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readDirectiveSurface(sessionId, env = process.env) {
+  try {
+    const path = directivePath(sessionId, env);
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    const shownAt = Date.parse(String(parsed?.shown_at ?? ""));
+    if (
+      !parsed?.directive_id ||
+      !Number.isFinite(shownAt) ||
+      shownAt + DIRECTIVE_MARKER_TTL_MS < Date.now()
+    ) {
+      rmSync(path, { force: true });
+      return null;
+    }
+    return {
+      directive_id: safeText(parsed.directive_id, 96),
+      runtime: normalizeRuntime(parsed.runtime),
+      trigger_reason: safeText(
+        parsed.trigger_reason ?? "contextual_continuation",
+        160,
+      ),
+      shown_at: new Date(shownAt).toISOString(),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export async function recordDirectiveFollowThroughForTool(
+  sessionId,
+  toolName,
+  rawResponse,
+  options = {},
+) {
+  const normalizedTool = String(toolName ?? "")
+    .trim()
+    .toLowerCase();
+  if (
+    !normalizedTool.endsWith("query_skills") ||
+    (normalizedTool !== "query_skills" &&
+      !normalizedTool.includes("remembrance"))
+  ) {
+    return false;
+  }
+  const env = options.env ?? process.env;
+  const directive = readDirectiveSurface(sessionId, env);
+  if (!directive) return false;
+  // A completed query consumes this task directive even if its response shape
+  // prevents correlation; never let a later unrelated query claim it.
+  recordDirectiveSurface(sessionId, null, env);
+  const queryId = queryIdFromToolResponse(rawResponse);
+  if (!queryId) return false;
+  return reportDirectiveEvent(
+    {
+      event: "followed",
+      directive_id: directive.directive_id,
+      query_id: queryId,
+    },
+    options,
+  );
+}
+
+function queryIdFromToolResponse(value, depth = 0) {
+  if (depth > 5 || value === null || value === undefined) return null;
+  if (typeof value === "string") {
+    try {
+      return queryIdFromToolResponse(JSON.parse(value), depth + 1);
+    } catch {
+      return null;
+    }
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const queryId = queryIdFromToolResponse(item, depth + 1);
+      if (queryId) return queryId;
+    }
+    return null;
+  }
+  if (typeof value !== "object") return null;
+  if (typeof value.query_id === "string" && value.query_id.trim()) {
+    return safeText(value.query_id, 80);
+  }
+  if (value.type === "text" && typeof value.text === "string") {
+    const queryId = queryIdFromToolResponse(value.text, depth + 1);
+    if (queryId) return queryId;
+  }
+  for (const key of [
+    "body",
+    "result",
+    "output",
+    "response",
+    "tool_response",
+    "toolResponse",
+    "content",
+  ]) {
+    const queryId = queryIdFromToolResponse(value[key], depth + 1);
+    if (queryId) return queryId;
+  }
+  return null;
+}
+
+export function responseBodyFromToolResponse(value, depth = 0) {
+  if (depth > 6 || value === null || value === undefined) return null;
+  if (typeof value === "string") {
+    try {
+      return responseBodyFromToolResponse(JSON.parse(value), depth + 1);
+    } catch {
+      return null;
+    }
+  }
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      const body = responseBodyFromToolResponse(item, depth + 1);
+      if (body) return body;
+    }
+    return null;
+  }
+  if (typeof value !== "object") return null;
+  if (
+    typeof value.query_id === "string" ||
+    value.selection_mode === "explicit" ||
+    (value.next_step && typeof value.next_step === "object") ||
+    Array.isArray(value.skills) ||
+    Array.isArray(value.resources)
+  ) {
+    return value;
+  }
+  if (value.type === "text" && typeof value.text === "string") {
+    const body = responseBodyFromToolResponse(value.text, depth + 1);
+    if (body) return body;
+  }
+  for (const key of [
+    "body",
+    "result",
+    "output",
+    "response",
+    "tool_response",
+    "toolResponse",
+    "content",
+  ]) {
+    const body = responseBodyFromToolResponse(value[key], depth + 1);
+    if (body) return body;
+  }
+  return null;
+}
+
+export function responseRequestsRemembranceFollowup(response) {
+  const payload =
+    responseBodyFromToolResponse(response)?.next_step
+      ?.submit_remembrance_payload;
+  return Boolean(
+    payload && typeof payload === "object" && !Array.isArray(payload),
+  );
+}
+
+export function toolResponseIndicatesFailure(value, depth = 0) {
+  if (depth > 6 || value === null || value === undefined) return false;
+  if (typeof value === "string") {
+    try {
+      return toolResponseIndicatesFailure(JSON.parse(value), depth + 1);
+    } catch {
+      return false;
+    }
+  }
+  if (Array.isArray(value)) {
+    return value.some((item) => toolResponseIndicatesFailure(item, depth + 1));
+  }
+  if (typeof value !== "object") return false;
+  if (
+    value.ok === false ||
+    value.isError === true ||
+    value.is_error === true ||
+    (typeof value.status === "number" && value.status >= 400)
+  ) {
+    return true;
+  }
+  if (value.type === "text" && typeof value.text === "string") {
+    return toolResponseIndicatesFailure(value.text, depth + 1);
+  }
+  for (const key of [
+    "result",
+    "output",
+    "response",
+    "tool_response",
+    "toolResponse",
+    "content",
+  ]) {
+    if (toolResponseIndicatesFailure(value[key], depth + 1)) return true;
+  }
+  return false;
+}
+
+export function directSelectionFromResponse(response) {
+  const body = responseBodyFromToolResponse(response);
+  const skill = body?.skill;
+  if (
+    body?.selection_mode !== "explicit" ||
+    !skill ||
+    typeof skill.slug !== "string" ||
+    !skill.slug.trim() ||
+    typeof skill.skill_md !== "string" ||
+    !skill.skill_md.trim()
+  ) {
+    return null;
+  }
+  return {
+    invocation_id:
+      typeof body.invocation_id === "string"
+        ? safeText(body.invocation_id, 80)
+        : null,
+    query_id:
+      typeof body.query_id === "string" ? safeText(body.query_id, 80) : null,
+    result_id:
+      typeof body.result_id === "string" ? safeText(body.result_id, 80) : null,
+    slug: safeText(skill.slug, 120),
+    version:
+      skill.version === null || skill.version === undefined
+        ? null
+        : safeText(skill.version, 80),
+    version_id:
+      typeof skill.version_id === "string"
+        ? safeText(skill.version_id, 80)
+        : null,
+    source:
+      typeof skill.source === "string" ? safeText(skill.source, 40) : null,
+    feedback_available: body?.feedback?.available === true,
+    task_outcome_available: body?.task_outcome?.available === true,
+    used_at: new Date().toISOString(),
+  };
+}
+
+export function recordDirectSelectionSurface(
+  sessionId,
+  selection,
+  env = process.env,
+) {
+  const path = directSelectionPath(sessionId, env);
+  try {
+    if (!selection) {
+      rmSync(path, { force: true });
+      return true;
+    }
+    const normalized = normalizeDirectSelectionSurface(
+      selection,
+      sessionId,
+      env,
+    );
+    const records = readDirectSelectionSurfaces(sessionId, env).filter(
+      (item) =>
+        !normalized.query_id ||
+        !normalized.result_id ||
+        item.query_id !== normalized.query_id ||
+        item.result_id !== normalized.result_id,
+    );
+    records.push(normalized);
+    return writeDirectSelectionSurfaces(sessionId, records, env);
+  } catch {
+    return false;
+  }
+}
+
+export function readDirectSelectionSurfaces(sessionId, env = process.env) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(directSelectionPath(sessionId, env), "utf8"),
+    );
+    const records = (Array.isArray(parsed) ? parsed : [parsed])
+      .map((item) => normalizeStoredDirectSelectionSurface(item))
+      .filter(Boolean)
+      .filter(
+        (item) =>
+          Date.parse(item.used_at) + DIRECT_SELECTION_MARKER_TTL_MS >=
+          Date.now(),
+      )
+      .slice(-DIRECT_SELECTION_MARKER_LIMIT);
+    if (records.length === 0) {
+      rmSync(directSelectionPath(sessionId, env), { force: true });
+    }
+    return records;
+  } catch {
+    return [];
+  }
+}
+
+export function readDirectSelectionSurface(sessionId, env = process.env) {
+  return readDirectSelectionSurfaces(sessionId, env).at(-1) ?? null;
+}
+
+function normalizeDirectSelectionSurface(selection, sessionId, env) {
+  return {
+    invocation_id: selection.invocation_id
+      ? safeText(selection.invocation_id, 80)
+      : null,
+    query_id: selection.query_id ? safeText(selection.query_id, 80) : null,
+    result_id: selection.result_id ? safeText(selection.result_id, 80) : null,
+    slug: safeText(selection.slug, 120),
+    version: selection.version ? safeText(selection.version, 80) : null,
+    version_id: selection.version_id
+      ? safeText(selection.version_id, 80)
+      : null,
+    source: selection.source ? safeText(selection.source, 40) : null,
+    feedback_available: selection.feedback_available === true,
+    task_outcome_available: selection.task_outcome_available === true,
+    prompted_at: selection.prompted_at
+      ? safeText(selection.prompted_at, 40)
+      : null,
+    use_count: Number.isFinite(selection.use_count)
+      ? Math.max(0, Math.round(selection.use_count))
+      : readRegistryUseCount(sessionId, env),
+    used_at: safeText(selection.used_at ?? new Date().toISOString(), 40),
+  };
+}
+
+function normalizeStoredDirectSelectionSurface(selection) {
+  const usedAt = Date.parse(String(selection?.used_at ?? ""));
+  if (!selection?.slug || !Number.isFinite(usedAt)) return null;
+  return {
+    invocation_id: selection.invocation_id
+      ? safeText(selection.invocation_id, 80)
+      : null,
+    query_id: selection.query_id ? safeText(selection.query_id, 80) : null,
+    result_id: selection.result_id ? safeText(selection.result_id, 80) : null,
+    slug: safeText(selection.slug, 120),
+    version: selection.version ? safeText(selection.version, 80) : null,
+    version_id: selection.version_id
+      ? safeText(selection.version_id, 80)
+      : null,
+    source: selection.source ? safeText(selection.source, 40) : null,
+    feedback_available: selection.feedback_available === true,
+    task_outcome_available: selection.task_outcome_available === true,
+    prompted_at: selection.prompted_at
+      ? safeText(selection.prompted_at, 40)
+      : null,
+    use_count: Number.isFinite(selection.use_count)
+      ? Math.max(0, Math.round(selection.use_count))
+      : 0,
+    used_at: new Date(usedAt).toISOString(),
+  };
+}
+
+function writeDirectSelectionSurfaces(sessionId, records, env) {
+  try {
+    const path = directSelectionPath(sessionId, env);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify(records.slice(-DIRECT_SELECTION_MARKER_LIMIT)),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function markDirectSelectionSurfacesPrompted(
+  sessionId,
+  useCount,
+  env = process.env,
+) {
+  const records = readDirectSelectionSurfaces(sessionId, env);
+  const now = new Date().toISOString();
+  let changed = false;
+  for (const selection of records) {
+    if (
+      !selection.prompted_at &&
+      Number.isFinite(selection.use_count) &&
+      selection.use_count <= useCount
+    ) {
+      selection.prompted_at = now;
+      changed = true;
+    }
+  }
+  return changed
+    ? writeDirectSelectionSurfaces(sessionId, records, env)
+    : false;
+}
+
+export function clearHighMatchSurfaceForExplicitSelection(
+  sessionId,
+  slug,
+  env = process.env,
+) {
+  const match = readHighMatchSurface(sessionId, env);
+  if (!match || match.target_type !== "skill" || match.slug !== String(slug)) {
+    return false;
+  }
+  return recordHighMatchSurface(sessionId, null, env);
+}
+
+// Store only bounded public result metadata. A later completed query replaces
+// or clears the marker, so Stop never repeats a stale high-match instruction.
+export function recordHighMatchSurface(sessionId, match, env = process.env) {
+  const path = highMatchPath(sessionId, env);
+  try {
+    if (!match) {
+      rmSync(path, { force: true });
+      return true;
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify({
+        query_id: match.query_id ? safeText(match.query_id, 80) : null,
+        result_id: match.result_id ? safeText(match.result_id, 80) : null,
+        target_type: match.target_type === "resource" ? "resource" : "skill",
+        slug: safeText(match.slug, 120),
+        match_reason: safeText(
+          match.match_reason ?? "Strong task coverage",
+          160,
+        ),
+        estimated_tokens: Number.isFinite(match.estimated_tokens)
+          ? Math.max(0, Math.round(match.estimated_tokens))
+          : null,
+        verified_uses: numberValue(match.verified_uses),
+        risk_level: safeText(match.risk_level ?? "unknown", 24),
+        value_estimate_id: match.value_estimate_id
+          ? safeText(match.value_estimate_id, 80)
+          : null,
+        potential_savings: sanitizePotentialSavings(match.potential_savings),
+      }),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function readHighMatchSurface(sessionId, env = process.env) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(highMatchPath(sessionId, env), "utf8"),
+    );
+    if (!parsed || typeof parsed.slug !== "string" || !parsed.slug.trim()) {
+      return null;
+    }
+    return {
+      query_id:
+        typeof parsed.query_id === "string"
+          ? safeText(parsed.query_id, 80)
+          : null,
+      result_id:
+        typeof parsed.result_id === "string"
+          ? safeText(parsed.result_id, 80)
+          : null,
+      target_type: parsed.target_type === "resource" ? "resource" : "skill",
+      slug: safeText(parsed.slug, 120),
+      match_reason: safeText(
+        parsed.match_reason ?? "Strong task coverage",
+        160,
+      ),
+      estimated_tokens: Number.isFinite(parsed.estimated_tokens)
+        ? Math.max(0, Math.round(parsed.estimated_tokens))
+        : null,
+      verified_uses: numberValue(parsed.verified_uses),
+      risk_level: safeText(parsed.risk_level ?? "unknown", 24),
+      value_estimate_id:
+        typeof parsed.value_estimate_id === "string"
+          ? safeText(parsed.value_estimate_id, 80)
+          : null,
+      potential_savings: sanitizePotentialSavings(parsed.potential_savings),
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function clearHighMatchSurfaceIfOpened(
+  sessionId,
+  toolName,
+  rawArguments,
+  env = process.env,
+) {
+  const normalizedTool = String(toolName ?? "")
+    .trim()
+    .toLowerCase();
+  const targetType = normalizedTool.endsWith("get_resource")
+    ? "resource"
+    : normalizedTool.endsWith("get_skill")
+      ? "skill"
+      : null;
+  if (
+    !targetType ||
+    (normalizedTool !== `get_${targetType}` &&
+      !normalizedTool.includes("remembrance"))
+  ) {
+    return false;
+  }
+  const args =
+    rawArguments && typeof rawArguments === "object" ? rawArguments : {};
+  const match = readHighMatchSurface(sessionId, env);
+  if (!match || match.target_type !== targetType) return false;
+  if (String(args.slug ?? "") !== match.slug) return false;
+  if (match.query_id && String(args.query_id ?? "") !== match.query_id) {
+    return false;
+  }
+  if (match.result_id && String(args.result_id ?? "") !== match.result_id) {
+    return false;
+  }
+  markValueEpisodeSelection(
+    sessionId,
+    String(args.query_id ?? match.query_id ?? ""),
+    String(args.result_id ?? match.result_id ?? ""),
+    env,
+  );
+  return recordHighMatchSurface(sessionId, null, env);
+}
+
+export function valueEpisodeFromResponse(response) {
+  const body = responseBodyFromToolResponse(response);
+  const queryId = body?.query_id ?? body?.query_feedback?.query_id;
+  if (!queryId || body?.task_outcome?.available !== true) return null;
+  const eligibleResultIds = new Set(
+    Array.isArray(body?.task_outcome?.eligible_result_ids)
+      ? body.task_outcome.eligible_result_ids.map((id) => String(id))
+      : [],
+  );
+  if (eligibleResultIds.size === 0) return null;
+  const directSelection = body?.selection_mode === "explicit";
+  const candidates = [
+    ...(directSelection && body?.skill
+      ? [
+          {
+            ...body.skill,
+            result_id: body.result_id,
+            task_outcome_eligible:
+              body.skill.task_outcome_eligible === true &&
+              body?.task_outcome?.eligible_result_ids?.includes(body.result_id),
+          },
+        ]
+      : []),
+    ...(Array.isArray(body?.skills) ? body.skills : []),
+    ...(Array.isArray(body?.resources) ? body.resources : []),
+  ]
+    .filter(
+      (item) =>
+        item?.task_outcome_eligible === true &&
+        item?.result_id &&
+        eligibleResultIds.has(String(item.result_id)),
+    )
+    .slice(0, 40)
+    .map((item) => ({
+      result_id: safeText(item.result_id, 80),
+      value_estimate_id: item.value_estimate_id
+        ? safeText(item.value_estimate_id, 80)
+        : null,
+    }));
+  const bundles = (Array.isArray(body?.skill_bundles) ? body.skill_bundles : [])
+    .filter((bundle) => {
+      const resultIds = Array.isArray(bundle?.result_ids)
+        ? bundle.result_ids.map((id) => String(id))
+        : [];
+      return (
+        bundle?.task_outcome_eligible === true &&
+        bundle?.bundle_id &&
+        resultIds.length > 0 &&
+        resultIds.length <= 3 &&
+        resultIds.every((resultId) => eligibleResultIds.has(resultId))
+      );
+    })
+    .slice(0, 20)
+    .map((bundle) => ({
+      bundle_id: safeText(bundle.bundle_id, 80),
+      result_ids: bundle.result_ids.slice(0, 3).map((id) => safeText(id, 80)),
+      value_estimate_id: bundle.value_estimate_id
+        ? safeText(bundle.value_estimate_id, 80)
+        : null,
+    }));
+  return {
+    query_id: safeText(queryId, 80),
+    interaction_kind: directSelection ? "direct_selection" : "query",
+    candidates,
+    bundles,
+    selected_result_ids:
+      directSelection && candidates[0]?.result_id
+        ? [candidates[0].result_id]
+        : [],
+    feedback_available: directSelection
+      ? body?.feedback?.available === true
+      : true,
+    created_at: new Date().toISOString(),
+    reported_at: null,
+  };
+}
+
+export function recordValueEpisodeSurface(
+  sessionId,
+  episode,
+  env = process.env,
+) {
+  if (!episode?.query_id) return false;
+  const records = readValueEpisodeSurfaces(sessionId, env).filter(
+    (item) => item.query_id !== episode.query_id,
+  );
+  records.push(episode);
+  return writeValueEpisodeSurfaces(
+    sessionId,
+    records.slice(-VALUE_EPISODE_MARKER_LIMIT),
+    env,
+  );
+}
+
+export function readValueEpisodeSurfaces(sessionId, env = process.env) {
+  try {
+    const parsed = JSON.parse(
+      readFileSync(valueEpisodePath(sessionId, env), "utf8"),
+    );
+    if (!Array.isArray(parsed)) return [];
+    return parsed
+      .filter((item) => {
+        const createdAt = Date.parse(String(item?.created_at ?? ""));
+        return (
+          item &&
+          typeof item.query_id === "string" &&
+          Number.isFinite(createdAt) &&
+          createdAt + VALUE_EPISODE_MARKER_TTL_MS > Date.now()
+        );
+      })
+      .slice(-VALUE_EPISODE_MARKER_LIMIT)
+      .map((item) => ({
+        query_id: safeText(item.query_id, 80),
+        interaction_kind:
+          item.interaction_kind === "direct_selection"
+            ? "direct_selection"
+            : "query",
+        candidates: Array.isArray(item.candidates)
+          ? item.candidates.slice(0, 40).map((candidate) => ({
+              result_id: safeText(candidate?.result_id, 80),
+              value_estimate_id: candidate?.value_estimate_id
+                ? safeText(candidate.value_estimate_id, 80)
+                : null,
+            }))
+          : [],
+        bundles: Array.isArray(item.bundles)
+          ? item.bundles.slice(0, 20).map((bundle) => ({
+              bundle_id: safeText(bundle?.bundle_id, 80),
+              result_ids: Array.isArray(bundle?.result_ids)
+                ? bundle.result_ids.slice(0, 3).map((id) => safeText(id, 80))
+                : [],
+              value_estimate_id: bundle?.value_estimate_id
+                ? safeText(bundle.value_estimate_id, 80)
+                : null,
+            }))
+          : [],
+        selected_result_ids: Array.isArray(item.selected_result_ids)
+          ? item.selected_result_ids.slice(0, 3).map((id) => safeText(id, 80))
+          : [],
+        feedback_available: item.feedback_available !== false,
+        created_at: safeText(item.created_at ?? "", 40),
+        reported_at: item.reported_at ? safeText(item.reported_at, 40) : null,
+      }));
+  } catch {
+    return [];
+  }
+}
+
+export function markValueEpisodeSelection(
+  sessionId,
+  queryId,
+  resultId,
+  env = process.env,
+) {
+  if (!queryId || !resultId) return false;
+  const records = readValueEpisodeSurfaces(sessionId, env);
+  const record = records.find((item) => item.query_id === queryId);
+  if (
+    !record ||
+    !record.candidates.some((item) => item.result_id === resultId)
+  ) {
+    return false;
+  }
+  record.selected_result_ids = [
+    ...new Set([...record.selected_result_ids, resultId]),
+  ].slice(0, 3);
+  return writeValueEpisodeSurfaces(sessionId, records, env);
+}
+
+export async function reportTaskOutcomesOnStop(sessionId, input, options = {}) {
+  const env = options.env ?? process.env;
+  const records = readValueEpisodeSurfaces(sessionId, env);
+  const pending = records.filter((item) => !item.reported_at).slice(0, 5);
+  if (pending.length === 0) return 0;
+  const tokenUsage = tokenUsageFromRuntime(input);
+  const modelRevision = stringOrNull(
+    input?.observed_model_revision ??
+      input?.model_revision ??
+      input?.model ??
+      env.REMEMBRANCE_OBSERVED_MODEL_REVISION,
+  );
+  const reasoningEffort = normalizeReasoningEffort(
+    input?.reasoning_effort ?? env.REMEMBRANCE_REASONING_EFFORT,
+  );
+  let recorded = 0;
+  for (const episode of pending) {
+    const selected = episode.selected_result_ids.slice(0, 3);
+    const selectedKey = [...selected].sort().join("\u0000");
+    const selectedBundle = episode.bundles.find(
+      (bundle) => [...bundle.result_ids].sort().join("\u0000") === selectedKey,
+    );
+    const estimateId = selectedBundle?.value_estimate_id
+      ? selectedBundle.value_estimate_id
+      : selected.length === 1
+        ? episode.candidates.find((item) => item.result_id === selected[0])
+            ?.value_estimate_id
+        : null;
+    const response = await postTaskOutcome(
+      {
+        query_id: episode.query_id,
+        result_ids: selected,
+        estimate_id: estimateId ?? null,
+        bundle_id: selectedBundle?.bundle_id ?? null,
+        status: "completed",
+        success: null,
+        latency_ms: null,
+        token_usage: tokenUsage,
+        observed_model_revision: modelRevision,
+        reasoning_effort: reasoningEffort,
+        provider_response_ids: [],
+        measurement_source: "plugin_observed",
+        idempotency_key: `hook_${sessionHash(sessionId)}_${safeText(episode.query_id, 64)}`,
+      },
+      {
+        env,
+        fetchImpl: options.fetchImpl ?? fetch,
+        userAgent: options.userAgent,
+      },
+    );
+    if (response) {
+      episode.reported_at = new Date().toISOString();
+      recorded += 1;
+    }
+  }
+  writeValueEpisodeSurfaces(sessionId, records, env);
+  return recorded;
+}
+
+async function postTaskOutcome(payload, options = {}) {
+  const env = options.env ?? process.env;
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), autoQueryTimeoutMs(env));
+  try {
+    const credential = resolveApiCredential(env);
+    if (isUnusableConfigurationSource(credential.source)) return false;
+    const headers = {
+      "content-type": "application/json",
+      "user-agent": options.userAgent ?? DEFAULT_USER_AGENT,
+    };
+    const apiKey = credential.apiKey;
+    if (apiKey) headers["x-remembrance-api-key"] = apiKey;
+    const response = await (options.fetchImpl ?? fetch)(
+      `${apiUrl(env)}/api/v1/agent/task-outcomes`,
+      {
+        method: "POST",
+        headers,
+        body: JSON.stringify(payload),
+        signal: controller.signal,
+      },
+    );
+    return Boolean(response?.ok);
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+function writeValueEpisodeSurfaces(sessionId, records, env) {
+  try {
+    const path = valueEpisodePath(sessionId, env);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(
+      path,
+      JSON.stringify(records.slice(-VALUE_EPISODE_MARKER_LIMIT)),
+    );
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function tokenUsageFromRuntime(input) {
+  const usage =
+    input?.token_usage ??
+    input?.tokenUsage ??
+    input?.usage ??
+    input?.model_usage;
+  if (!usage || typeof usage !== "object") return null;
+  const inputTokens = finiteNonNegative(
+    usage.input_tokens ?? usage.inputTokens ?? usage.prompt_tokens,
+  );
+  const outputTokens = finiteNonNegative(
+    usage.output_tokens ?? usage.outputTokens ?? usage.completion_tokens,
+  );
+  if (inputTokens === null || outputTokens === null) return null;
+  const cacheRead =
+    finiteNonNegative(usage.cache_read_tokens ?? usage.cacheReadTokens) ?? 0;
+  const cacheWrite =
+    finiteNonNegative(usage.cache_write_tokens ?? usage.cacheWriteTokens) ?? 0;
+  const reasoning =
+    finiteNonNegative(usage.reasoning_tokens ?? usage.reasoningTokens) ?? 0;
+  return {
+    uncached_input_tokens: Math.max(0, inputTokens - cacheRead - cacheWrite),
+    cache_read_tokens: cacheRead,
+    cache_write_tokens: cacheWrite,
+    visible_output_tokens: Math.max(0, outputTokens - reasoning),
+    reasoning_tokens: reasoning,
+  };
+}
+
+function finiteNonNegative(value) {
+  const number = Number(value);
+  return Number.isFinite(number) && number >= 0 ? Math.round(number) : null;
+}
+
+function normalizeReasoningEffort(value) {
+  const normalized = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  return ["none", "minimal", "low", "medium", "high", "max"].includes(
+    normalized,
+  )
+    ? normalized
+    : "unknown";
+}
+
+function sanitizePotentialSavings(value) {
+  if (!value || typeof value !== "object") return null;
+  const estimated = value.estimated_saved;
+  if (!estimated || typeof estimated !== "object") return null;
+  const low = finiteNonNegative(estimated.low);
+  const medianValue = finiteNonNegative(estimated.median);
+  const high = finiteNonNegative(estimated.high);
+  if (low === null || medianValue === null || high === null) return null;
+  return {
+    unit: "tokens",
+    context_tokens: finiteNonNegative(value.context_tokens) ?? 0,
+    estimated_saved: { low, median: medianValue, high },
+    proof_grade: value.proof_grade === "A" ? "A" : "B",
+    measured_episodes: finiteNonNegative(value.measured_episodes) ?? 0,
+    proof_url: safeText(value.proof_url ?? "", 300),
+    caveat: "Estimate, not a guarantee.",
+  };
+}
+
+function potentialSavingsLabel(value) {
+  const savings = sanitizePotentialSavings(value);
+  if (!savings) return null;
+  return `${formatCompactNumber(savings.estimated_saved.low)}-${formatCompactNumber(savings.estimated_saved.high)} potential tokens saved (grade ${savings.proof_grade} signed proof)`;
+}
+
+function formatCompactNumber(value) {
+  if (value >= 1000) {
+    const rounded = Math.round((value / 1000) * 10) / 10;
+    return `${rounded}k`;
+  }
+  return String(value);
+}
+
+// Read the use count at which this session was last prompted to contribute.
+export function readPromptedCount(sessionId, env = process.env) {
+  return readCountFile(promptPath(sessionId, env));
+}
+
+// Record the use count at which we just prompted this session.
+export function writePromptedCount(sessionId, count, env = process.env) {
+  const written = writeCountFile(promptPath(sessionId, env), count);
+  if (written) {
+    markDirectSelectionSurfacesPrompted(sessionId, count, env);
+  }
+  return written;
+}
+
+// --- Shared helpers ----------------------------------------------------------
+
+export function sessionIdFor(input) {
+  return input?.turn_id ?? input?.session_id ?? "unknown";
+}
+
+export function disabled(value) {
+  return /^(0|false|no)$/i.test(String(value ?? ""));
+}
+
+export function contributeDisabled(value) {
+  return /^(0|false|no)$/i.test(String(value ?? "").trim());
+}
+
+function pluginHealthDir(env = process.env) {
+  return env?.REMEMBRANCE_PLUGIN_HEALTH_DIR
+    ? String(env.REMEMBRANCE_PLUGIN_HEALTH_DIR)
+    : join(tmpdir(), PLUGIN_HEALTH_DIR);
+}
+
+function normalizedPluginHealthSurface(value) {
+  const surface = String(value ?? "")
+    .trim()
+    .toLowerCase();
+  return PLUGIN_HEALTH_SURFACES.has(surface) ? surface : null;
+}
+
+export function pluginHealthPath(surface, env = process.env) {
+  return pluginHealthSessionPath(surface, null, env);
+}
+
+function pluginHealthSessionPath(surface, sessionId, env = process.env) {
+  const normalized = normalizedPluginHealthSurface(surface);
+  if (!normalized) return null;
+  const normalizedSession = safeText(sessionId ?? "", 256);
+  if (!normalizedSession || normalizedSession === "unknown") {
+    return join(pluginHealthDir(env), `${normalized}.json`);
+  }
+  const sessionHash = createHash("sha256")
+    .update(normalizedSession, "utf8")
+    .digest("hex")
+    .slice(0, 24);
+  return join(pluginHealthDir(env), `${normalized}.${sessionHash}.json`);
+}
+
+export function readPluginLifecycleHealth(
+  surface,
+  env = process.env,
+  sessionId = null,
+) {
+  const path = pluginHealthSessionPath(surface, sessionId, env);
+  if (!path) return null;
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+// Record that a native lifecycle component actually executed. The marker is
+// intentionally local and content-free: it contains only surface/version,
+// component timestamps, and the credential source category. Local MCP reads
+// it through get_connection_status so partial activation cannot look healthy.
+export function recordPluginLifecycleHealth(
+  {
+    surface,
+    component,
+    pluginVersion = null,
+    hostVersion = null,
+    credentialSource = null,
+    sessionId = null,
+  },
+  env = process.env,
+) {
+  const normalizedSurface = normalizedPluginHealthSurface(surface);
+  const normalizedComponent = String(component ?? "")
+    .trim()
+    .toLowerCase();
+  if (
+    !normalizedSurface ||
+    !PLUGIN_HEALTH_COMPONENTS.has(normalizedComponent)
+  ) {
+    return false;
+  }
+  const path = pluginHealthSessionPath(normalizedSurface, sessionId, env);
+  if (!path) return false;
+  const now = new Date().toISOString();
+  let existing =
+    readPluginLifecycleHealth(normalizedSurface, env, sessionId) ?? {};
+  // Hosts may emit SessionStart without the stable session id later supplied
+  // to prompt/tool/completion hooks. Seed that startup observation into the
+  // first session-specific marker, but never copy another session's later
+  // components.
+  if (
+    sessionId &&
+    sessionId !== "unknown" &&
+    Object.keys(existing).length === 0 &&
+    normalizedComponent !== "session_start"
+  ) {
+    const startup = readPluginLifecycleHealth(normalizedSurface, env);
+    const startupComponents =
+      startup?.components &&
+      typeof startup.components === "object" &&
+      !Array.isArray(startup.components) &&
+      typeof startup.components.session_start === "string"
+        ? { session_start: startup.components.session_start }
+        : {};
+    existing = {
+      ...(startup ?? {}),
+      components: startupComponents,
+    };
+  }
+  const existingComponents =
+    existing.components &&
+    typeof existing.components === "object" &&
+    !Array.isArray(existing.components)
+      ? existing.components
+      : {};
+  // A new host session must not inherit prompt/tool/completion observations
+  // from a prior session. Otherwise a current partial activation could look
+  // healthy for as long as the old marker remains fresh.
+  const currentComponents =
+    normalizedComponent === "session_start" ? {} : existingComponents;
+  const payload = {
+    schema_version: 1,
+    surface: normalizedSurface,
+    session_hash:
+      sessionId && sessionId !== "unknown"
+        ? createHash("sha256")
+            .update(String(sessionId), "utf8")
+            .digest("hex")
+            .slice(0, 24)
+        : null,
+    plugin_version: safeText(
+      pluginVersion ?? existing.plugin_version ?? "",
+      64,
+    ),
+    host_version: safeText(hostVersion ?? existing.host_version ?? "", 64),
+    credential_source: ["environment", "shared_config", "none"].includes(
+      credentialSource,
+    )
+      ? credentialSource
+      : ["environment", "shared_config", "none"].includes(
+            existing.credential_source,
+          )
+        ? existing.credential_source
+        : "none",
+    components: {
+      ...currentComponents,
+      [normalizedComponent]: now,
+    },
+    last_seen_at: now,
+  };
+  const temporaryPath = `${path}.${process.pid}.${randomBytes(6).toString("hex")}.tmp`;
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(temporaryPath, `${JSON.stringify(payload)}\n`, {
+      mode: 0o600,
+    });
+    renameSync(temporaryPath, path);
+    prunePluginHealthSessionMarkers(normalizedSurface, path, env);
+    return true;
+  } catch {
+    try {
+      rmSync(temporaryPath, { force: true });
+    } catch {
+      // Health recording is best-effort and must never break a host hook.
+    }
+    return false;
+  }
+}
+
+function prunePluginHealthSessionMarkers(surface, keepPath, env) {
+  const directory = pluginHealthDir(env);
+  try {
+    const candidates = readdirSync(directory)
+      .filter(
+        (name) =>
+          name.startsWith(`${surface}.`) &&
+          /^[a-z_]+\.[a-f0-9]{24}\.json$/.test(name),
+      )
+      .map((name) => {
+        const path = join(directory, name);
+        return { path, modified: statSync(path).mtimeMs };
+      })
+      .sort((left, right) => right.modified - left.modified);
+    for (const candidate of candidates.slice(32)) {
+      if (candidate.path !== keepPath) rmSync(candidate.path, { force: true });
+    }
+  } catch {
+    // Pruning is advisory; health recording must remain fail-open.
+  }
+}
+
+// Well-known config file that carries the org API key (and, optionally, the API
+// URL). It exists so a plugin user can authenticate ONCE — via one copy-paste
+// command that writes this file — and have prompt hooks plus local/bundled MCP
+// servers pick the key up, regardless of how the runtime happens to pass (or
+// not pass) environment variables to hook commands. Hosted MCP cannot read a
+// file on the caller's machine and authenticates separately. Co-located with
+// the agent attestation key under the XDG config dir. General reads remain
+// best-effort for diagnostics; credential resolution separately distinguishes
+// an absent file from a present malformed file and blocks remote calls for the
+// latter instead of silently changing scope.
+export function remembranceConfigPath(env = process.env) {
+  return join(
+    env.XDG_CONFIG_HOME || join(homedir(), ".config"),
+    "remembrance",
+    "config.json",
+  );
+}
+
+export function readRemembranceConfig(env = process.env) {
+  try {
+    const parsed = JSON.parse(readFileSync(remembranceConfigPath(env), "utf8"));
+    return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      ? parsed
+      : {};
+  } catch {
+    return {};
+  }
+}
+
+export function resolveApiCredential(env = process.env) {
+  const apiConfiguration = resolveApiConfiguration(env);
+  if (isUnusableConfigurationSource(apiConfiguration.source)) {
+    return { apiKey: "", source: apiConfiguration.source };
+  }
+  const environmentKey = String(env.REMEMBRANCE_API_KEY ?? "").trim();
+  if (environmentKey) {
+    return {
+      apiKey: environmentKey,
+      source: "environment",
+    };
+  }
+  const path = remembranceConfigPath(env);
+  if (!existsSync(path)) {
+    return { apiKey: "", source: "none" };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return { apiKey: "", source: "unusable_shared_config" };
+    }
+    if (
+      Object.prototype.hasOwnProperty.call(parsed, "apiKey") &&
+      (typeof parsed.apiKey !== "string" || !parsed.apiKey.trim())
+    ) {
+      return { apiKey: "", source: "unusable_shared_config" };
+    }
+    const fromFile = parsed.apiKey;
+    return typeof fromFile === "string" && fromFile.trim()
+      ? { apiKey: fromFile.trim(), source: "shared_config" }
+      : { apiKey: "", source: "none" };
+  } catch {
+    return { apiKey: "", source: "unusable_shared_config" };
+  }
+}
+
+// The org API key: an explicit env var wins, then the config file. Returns ""
+// when neither is present (the request then goes out anonymously).
+export function resolveApiKey(env = process.env) {
+  return resolveApiCredential(env).apiKey;
+}
+
+export function sharedConfigCredentialNotice(env = process.env) {
+  const source = resolveApiCredential(env).source;
+  if (source === "unusable_environment") {
+    return (
+      "Remembrance setup needs attention: REMEMBRANCE_API_URL is invalid. " +
+      "Remote Remembrance calls are paused locally instead of changing " +
+      "destinations. Set it to an absolute HTTP(S) registry URL or " +
+      "intentionally remove it, then call get_connection_status."
+    );
+  }
+  if (source === "unusable_shared_config") {
+    return (
+      "Remembrance setup needs attention: the shared config file exists but " +
+      "is unreadable or invalid. Remote Remembrance calls are paused locally " +
+      "instead of falling back to anonymous scope. Fix or intentionally remove " +
+      "~/.config/remembrance/config.json, then call get_connection_status."
+    );
+  }
+  if (source !== "shared_config") {
+    return null;
+  }
+  return (
+    `Remembrance credential source: this plugin hook resolved its key from ` +
+    `the shared Remembrance config file (normally ` +
+    `~/.config/remembrance/config.json). REMEMBRANCE_API_KEY may be unset; do not ` +
+    `use an anonymous REST/browser probe to infer this hook's scope. Call ` +
+    `get_connection_status for the MCP transport you will use.`
+  );
+}
+
+export function resolveApiConfiguration(env = process.env) {
+  const environmentUrl = String(env.REMEMBRANCE_API_URL ?? "").trim();
+  if (environmentUrl) {
+    const normalized = normalizeApiUrl(environmentUrl);
+    return normalized
+      ? { apiUrl: normalized, source: "environment" }
+      : { apiUrl: DEFAULT_API_URL, source: "unusable_environment" };
+  }
+  const path = remembranceConfigPath(env);
+  if (!existsSync(path)) {
+    return { apiUrl: DEFAULT_API_URL, source: "default" };
+  }
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {
+        apiUrl: DEFAULT_API_URL,
+        source: "unusable_shared_config",
+      };
+    }
+    if (!Object.prototype.hasOwnProperty.call(parsed, "apiUrl")) {
+      return { apiUrl: DEFAULT_API_URL, source: "default" };
+    }
+    const normalized = normalizeApiUrl(parsed.apiUrl);
+    return normalized
+      ? { apiUrl: normalized, source: "shared_config" }
+      : { apiUrl: DEFAULT_API_URL, source: "unusable_shared_config" };
+  } catch {
+    return { apiUrl: DEFAULT_API_URL, source: "unusable_shared_config" };
+  }
+}
+
+function apiUrl(env) {
+  return resolveApiConfiguration(env).apiUrl;
+}
+
+function normalizeApiUrl(value) {
+  if (typeof value !== "string" || !value.trim()) return null;
+  const candidate = value.trim();
+  try {
+    const parsed = new URL(candidate);
+    if (
+      !["http:", "https:"].includes(parsed.protocol) ||
+      parsed.username ||
+      parsed.password ||
+      parsed.search ||
+      parsed.hash
+    ) {
+      return null;
+    }
+    return candidate.replace(/\/+$/, "");
+  } catch {
+    return null;
+  }
+}
+
+function isUnusableConfigurationSource(source) {
+  return (
+    source === "unusable_environment" || source === "unusable_shared_config"
+  );
+}
+
+// A manually configured hosted Codex MCP registration can diverge from the
+// hook runtime registry. The packaged Codex plugin now uses its bundled local
+// MCP server, which resolves the same shared config as the hooks and therefore
+// has no split to warn about.
+export function hostedMcpSplitNotice(env = process.env) {
+  const hookBase = normalizeRegistryBaseUrl(apiUrl(env));
+  if (hookBase === normalizeRegistryBaseUrl(DEFAULT_API_URL)) {
+    return null;
+  }
+  const hostedMcp = resolveHostedMcpRegistry(env);
+  if (hostedMcp.apiBase === hookBase) {
+    return null;
+  }
+  return (
+    `Note: Remembrance prompt hooks are querying ${hookBase}, but Codex ` +
+    `hosted MCP tools are configured for ${hostedMcp.apiBase} ` +
+    `(${hostedMcp.source}). Update REMEMBRANCE_API_URL or the Codex MCP ` +
+    `configuration so both surfaces use the same registry.`
+  );
+}
+
+export function resolveHostedMcpRegistry(env = process.env) {
+  const codexMcpUrl = stringOrNull(env.REMEMBRANCE_CODEX_MCP_URL);
+  if (codexMcpUrl) {
+    return {
+      apiBase: normalizeRegistryBaseUrl(codexMcpUrl),
+      mcpUrl: codexMcpUrl,
+      source: "REMEMBRANCE_CODEX_MCP_URL",
+    };
+  }
+  const genericMcpUrl = stringOrNull(env.REMEMBRANCE_MCP_URL);
+  if (genericMcpUrl) {
+    return {
+      apiBase: normalizeRegistryBaseUrl(genericMcpUrl),
+      mcpUrl: genericMcpUrl,
+      source: "REMEMBRANCE_MCP_URL",
+    };
+  }
+
+  const config = readCodexMcpConfig(env);
+  if (config?.command) {
+    return {
+      apiBase: normalizeRegistryBaseUrl(apiUrl(env)),
+      mcpUrl: "local stdio",
+      source: "active Codex MCP config",
+    };
+  }
+  if (config?.url) {
+    return {
+      apiBase: normalizeRegistryBaseUrl(config.url),
+      mcpUrl: config.url,
+      source: "active Codex MCP config",
+    };
+  }
+
+  const packaged = readPackagedCodexMcpRegistration();
+  if (packaged?.command) {
+    return {
+      apiBase: normalizeRegistryBaseUrl(apiUrl(env)),
+      mcpUrl: "local stdio",
+      source: "bundled local Codex MCP server",
+    };
+  }
+  const packagedUrl = packaged?.url ?? `${DEFAULT_API_URL}/api/mcp`;
+  return {
+    apiBase: normalizeRegistryBaseUrl(packagedUrl),
+    mcpUrl: packagedUrl,
+    source: "packaged Codex MCP manifest",
+  };
+}
+
+export function resolveCodexHostedMcpRegistration(env = process.env) {
+  const config = readCodexMcpConfig(env);
+  if (config) {
+    return {
+      url: config.url,
+      ...(config.command ? { command: config.command } : {}),
+      credentialEnvVars: config.credentialEnvVars,
+      hasStaticCredential: config.hasStaticCredential,
+      source: "active Codex MCP config",
+    };
+  }
+  const packaged = readPackagedCodexMcpRegistration();
+  if (packaged) {
+    return {
+      ...packaged,
+      source: "packaged Codex MCP manifest",
+    };
+  }
+  return {
+    url: null,
+    credentialEnvVars: [],
+    hasStaticCredential: false,
+    source: "Codex MCP registration",
+  };
+}
+
+export function normalizeRegistryBaseUrl(value) {
+  const raw = String(value ?? "")
+    .trim()
+    .replace(/\/+$/, "");
+  if (!raw) {
+    return "";
+  }
+  try {
+    const url = new URL(raw);
+    let pathname = url.pathname.replace(/\/+$/, "");
+    if (pathname === "/api/mcp") {
+      pathname = "";
+    } else if (pathname.endsWith("/api/mcp")) {
+      pathname = pathname.slice(0, -"/api/mcp".length);
+    }
+    const normalized = `${url.origin}${pathname}`.replace(/\/+$/, "");
+    return normalized || url.origin;
+  } catch {
+    return raw.replace(/\/api\/mcp$/, "").replace(/\/+$/, "");
+  }
+}
+
+export function readCodexMcpConfig(env = process.env) {
+  for (const path of codexConfigPaths(env)) {
+    try {
+      if (!existsSync(path)) {
+        continue;
+      }
+      const registration = parseCodexMcpRegistration(
+        readFileSync(path, "utf8"),
+      );
+      if (registration) {
+        return { path, ...registration };
+      }
+    } catch {
+      // Fail open: a malformed/unreadable Codex config should not break hooks.
+    }
+  }
+  return null;
+}
+
+export function parseCodexMcpUrl(toml) {
+  return parseCodexMcpRegistration(toml)?.url ?? null;
+}
+
+export function parseCodexMcpRegistration(toml) {
+  let section = "";
+  let found = false;
+  let url = null;
+  let command = null;
+  const credentialEnvVars = new Set();
+  let hasStaticCredential = false;
+
+  for (const rawLine of String(toml ?? "").split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line || line.startsWith("#")) {
+      continue;
+    }
+    const sectionMatch = line.match(/^\[([^\]]+)\]$/);
+    if (sectionMatch) {
+      section = sectionMatch[1].trim().replace(/["']/g, "");
+      if (
+        section === "mcp_servers.remembrance" ||
+        section.startsWith("mcp_servers.remembrance.")
+      ) {
+        found = true;
+      }
+      continue;
+    }
+    if (
+      section !== "mcp_servers.remembrance" &&
+      !section.startsWith("mcp_servers.remembrance.")
+    ) {
+      continue;
+    }
+
+    const assignment = line.match(/^(.+?)\s*=\s*(.+)$/);
+    if (!assignment) {
+      continue;
+    }
+    const key = parseTomlKey(assignment[1]);
+    const value = assignment[2];
+
+    if (section === "mcp_servers.remembrance") {
+      if (key === "url") {
+        url = parseTomlString(value);
+      } else if (key === "command") {
+        command = parseTomlString(value);
+      } else if (key === "bearer_token_env_var") {
+        addCredentialEnvVar(credentialEnvVars, parseTomlString(value));
+      } else if (key === "env_http_headers") {
+        for (const [header, envName] of parseTomlInlineTable(value)) {
+          if (isRemembranceAuthHeader(header)) {
+            addCredentialEnvVar(credentialEnvVars, envName);
+          }
+        }
+      } else if (key === "http_headers" || key === "headers") {
+        hasStaticCredential ||= parseTomlInlineTable(value).some(([header]) =>
+          isRemembranceAuthHeader(header),
+        );
+      }
+    } else if (section === "mcp_servers.remembrance.env_http_headers") {
+      if (isRemembranceAuthHeader(key)) {
+        addCredentialEnvVar(credentialEnvVars, parseTomlString(value));
+      }
+    } else if (
+      section === "mcp_servers.remembrance.http_headers" ||
+      section === "mcp_servers.remembrance.headers"
+    ) {
+      hasStaticCredential ||= isRemembranceAuthHeader(key);
+    }
+  }
+
+  return found
+    ? {
+        url,
+        credentialEnvVars: [...credentialEnvVars],
+        hasStaticCredential,
+        ...(command ? { command } : {}),
+      }
+    : null;
+}
+
+function codexConfigPaths(env) {
+  const explicit = stringOrNull(env.REMEMBRANCE_CODEX_CONFIG_PATH);
+  if (explicit) {
+    return [explicit];
+  }
+  const codexHome = stringOrNull(env.CODEX_HOME) ?? join(homedir(), ".codex");
+  return [
+    join(process.cwd(), ".codex", "config.toml"),
+    join(codexHome, "config.toml"),
+  ];
+}
+
+function readPackagedCodexMcpRegistration() {
+  for (const relativePath of ["../.mcp.codex.json", "../.mcp.json"]) {
+    try {
+      const parsed = JSON.parse(
+        readFileSync(new URL(relativePath, import.meta.url), "utf8"),
+      );
+      const server = parsed?.mcpServers?.remembrance;
+      if (!server || typeof server !== "object" || Array.isArray(server)) {
+        continue;
+      }
+      const credentialEnvVars = new Set();
+      addCredentialEnvVar(
+        credentialEnvVars,
+        stringOrNull(server.bearer_token_env_var),
+      );
+      for (const [header, envName] of Object.entries(
+        server.env_http_headers ?? {},
+      )) {
+        if (isRemembranceAuthHeader(header)) {
+          addCredentialEnvVar(credentialEnvVars, stringOrNull(envName));
+        }
+      }
+      const staticHeaders = {
+        ...(server.http_headers ?? {}),
+        ...(server.headers ?? {}),
+      };
+      return {
+        url: stringOrNull(server.url),
+        ...(stringOrNull(server.command)
+          ? { command: stringOrNull(server.command) }
+          : {}),
+        credentialEnvVars: [...credentialEnvVars],
+        hasStaticCredential: Object.keys(staticHeaders).some((header) =>
+          isRemembranceAuthHeader(header),
+        ),
+      };
+    } catch {
+      // Hook-core is copied into multiple plugin packages; not every copy has a
+      // hosted Codex MCP manifest next to it.
+    }
+  }
+  return null;
+}
+
+function addCredentialEnvVar(target, value) {
+  if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(String(value ?? ""))) {
+    target.add(String(value));
+  }
+}
+
+function isRemembranceAuthHeader(value) {
+  return ["authorization", "x-remembrance-api-key", "x-api-key"].includes(
+    String(value ?? "")
+      .trim()
+      .toLowerCase(),
+  );
+}
+
+function parseTomlKey(value) {
+  return String(value ?? "")
+    .trim()
+    .replace(/^["']|["']$/g, "");
+}
+
+function parseTomlInlineTable(value) {
+  const entries = [];
+  const source = String(value ?? "").trim();
+  if (!source.startsWith("{") || !source.endsWith("}")) {
+    return entries;
+  }
+  const body = source.slice(1, -1);
+  const pattern =
+    /(?:^|,)\s*(?:"([^"]+)"|'([^']+)'|([A-Za-z0-9_-]+))\s*=\s*("(?:\\.|[^"])*"|'[^']*'|[^,}]+)/g;
+  let match;
+  while ((match = pattern.exec(body)) !== null) {
+    const key = match[1] ?? match[2] ?? match[3] ?? "";
+    const parsedValue = parseTomlString(match[4]);
+    if (key && parsedValue) {
+      entries.push([key, parsedValue]);
+    }
+  }
+  return entries;
+}
+
+function parseTomlString(value) {
+  const trimmed = String(value ?? "").trim();
+  if (!trimmed) {
+    return null;
+  }
+  const quote = trimmed[0];
+  if (quote === '"' || quote === "'") {
+    const end = trimmed.indexOf(quote, 1);
+    return end > 0 ? trimmed.slice(1, end) : null;
+  }
+  const unquoted = trimmed.split("#")[0]?.trim();
+  return unquoted || null;
+}
+
+function stringOrNull(value) {
+  const text = String(value ?? "").trim();
+  return text || null;
+}
+
+function limitFromEnv(env) {
+  const parsed = Number.parseInt(
+    String(env.REMEMBRANCE_AUTO_QUERY_LIMIT ?? ""),
+    10,
+  );
+  return Number.isFinite(parsed) && parsed > 0 && parsed <= 10
+    ? parsed
+    : DEFAULT_LIMIT;
+}
+
+export function autoQueryTimeoutMs(env = process.env) {
+  const parsed = Number.parseInt(
+    String(env.REMEMBRANCE_AUTO_QUERY_TIMEOUT_MS ?? ""),
+    10,
+  );
+  return Number.isFinite(parsed) && parsed >= 100 && parsed <= 30_000
+    ? parsed
+    : DEFAULT_TIMEOUT_MS;
+}
+
+function directiveEventTimeoutMs(env) {
+  const parsed = Number.parseInt(
+    String(env.REMEMBRANCE_DIRECTIVE_EVENT_TIMEOUT_MS ?? ""),
+    10,
+  );
+  return Number.isFinite(parsed) && parsed >= 100 && parsed <= 2_000
+    ? parsed
+    : DEFAULT_DIRECTIVE_EVENT_TIMEOUT_MS;
+}
+
+export function debugLog(env, event, fields = {}, options = {}) {
+  if (!debugEnabled(env?.REMEMBRANCE_DEBUG)) {
+    return;
+  }
+  const writer = options.stderr ?? process.stderr;
+  const body = redactPrompt(JSON.stringify({ event, ...fields })).slice(
+    0,
+    1000,
+  );
+  writer.write(`[remembrance] ${body}\n`);
+}
+
+function debugEnabled(value) {
+  return /^(1|true|yes)$/i.test(String(value ?? ""));
+}
+
+function errorName(error) {
+  return error instanceof Error ? error.name || error.message : "Error";
+}
+
+function stringValue(value) {
+  const text = String(value ?? "").trim();
+  return text || "unknown";
+}
+
+function safeText(value, maxLength) {
+  const text = redactPrompt(stringValue(value)).replace(/\s+/g, " ").trim();
+  if (text.length <= maxLength) {
+    return text;
+  }
+  return `${text.slice(0, Math.max(0, maxLength - 3)).trim()}...`;
+}
+
+function numberValue(value) {
+  return Number.isFinite(Number(value)) ? String(Number(value)) : "0";
+}