@pfoundation/ocadvisor 26.9.1 → 26.9.3

package/dist/ocAdvisor.js

@@ -1,12 +1,18 @@
 import { Database } from "bun:sqlite";
 import { appendFile } from "fs/promises";
 import { homedir } from "os";
-import { join } from "path";
+import { isAbsolute, join } from "path";
+import { resolveBenchmarkPaths } from "./benchmarkConfig.js";
+import { buildBenchmarkEvidence, } from "./benchmarkEvidence.js";
+import { createBenchmarkStore, } from "./benchmarkStore.js";
+import { resolveAdvisorProfile, resolveRequesterProfile, } from "./modelProfiles.js";
+import { runTypeSafeGate, } from "./typesafeGate.js";
+import { TYPESAFE_DEFAULTS, buildDecisionState, normalizeTypeSafeOptions, resolveTypeSafeConfig, } from "./typesafeState.js";
 const DB_PATH = join(homedir(), ".local/share/opencode/opencode.db");
 const METRICS_PATH = join(homedir(), ".local/share/opencode/ocAdvisor-metrics.jsonl");
 const ADVISOR_PROVIDER = "anthropic";
 const ADVISOR_MODEL = "claude-fable-5-1";
-const ADVISOR_VARIANT = "max";
+const ADVISOR_VARIANT = "xhigh";
 const ADVISOR_SESSION_TITLE = "advisor";
 // Sessions created before the ocAdvisor → advisor rename keep working: title
 // discovery accepts both, and the storage key below is unchanged.
@@ -24,6 +30,11 @@ const DEFAULT_ADVISOR_CONFIG = {
     timeoutMs: ADVISOR_TIMEOUT_MS,
     maxTranscriptChars: 0,
     agentEffort: null,
+    disabledForModels: [],
+    benchmarks: {},
+    typesafeSource: { disabled: false, overrides: {} },
+    typesafe: { enabled: false, settings: null, keyPresent: false },
+    typesafeSettings: null,
 };
 function normalizeVariant(value) {
     if (value === null || value === undefined)
@@ -72,6 +83,74 @@ function normalizeAgentEffort(value) {
     }
     return undefined;
 }
+// Exact `provider/model` IDs. A string is split on commas; blanks are
+// dropped. `undefined` means "not set" so a later source can keep the
+// previous list. An empty array or whitespace-only string clears it.
+function normalizeDisabledForModels(value) {
+    if (value === undefined)
+        return undefined;
+    const entries = typeof value === "string" ? value.split(",") : value;
+    if (!Array.isArray(entries) ||
+        entries.some((entry) => typeof entry !== "string")) {
+        throw new Error("disabledForModels must be a string array or comma-separated string.");
+    }
+    const refs = entries.map((entry) => entry.trim()).filter(Boolean);
+    for (const ref of refs) {
+        const slash = ref.indexOf("/");
+        if (slash <= 0 ||
+            slash === ref.length - 1 ||
+            ref.endsWith("/") ||
+            ref.includes("//") ||
+            /[\s#*?]/u.test(ref)) {
+            throw new Error("disabledForModels requires exact provider/model IDs without variants or wildcards.");
+        }
+    }
+    return [...new Set(refs)];
+}
+// `{ path, mappingsPath, matchAnyProvider }`. `undefined`/`null` means
+// "not set"; blank entries are dropped; unknown keys are ignored. Invalid
+// explicit values throw so misconfiguration fails fast at setup instead of
+// silently degrading to default benchmark data.
+function parseBooleanOption(name, value) {
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string") {
+        const lowered = value.trim().toLowerCase();
+        if (["true", "1", "yes", "on"].includes(lowered))
+            return true;
+        if (["false", "0", "no", "off", ""].includes(lowered))
+            return false;
+    }
+    throw new Error(`benchmarks.${name} must be true or false.`);
+}
+function normalizeBenchmarks(value) {
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("benchmarks must be an object with path options.");
+    }
+    const raw = value;
+    const out = {};
+    for (const key of ["path", "mappingsPath"]) {
+        const entry = raw[key];
+        if (entry === undefined || entry === null)
+            continue;
+        if (typeof entry !== "string") {
+            throw new Error(`benchmarks.${key} must be an absolute path.`);
+        }
+        const trimmed = entry.trim();
+        if (!trimmed)
+            continue;
+        if (!isAbsolute(trimmed)) {
+            throw new Error(`benchmarks.${key} must be an absolute path.`);
+        }
+        out[key] = trimmed;
+    }
+    if (raw.matchAnyProvider !== undefined && raw.matchAnyProvider !== null) {
+        out.matchAnyProvider = parseBooleanOption("matchAnyProvider", raw.matchAnyProvider);
+    }
+    return out;
+}
 function toBoundedInt(value, min) {
     const raw = typeof value === "number"
         ? value
@@ -108,7 +187,7 @@ function parseModelRef(ref) {
     }
     return out;
 }
-function applyAdvisorConfigSource(base, src) {
+function applyAdvisorConfigSource(base, src, env = process.env) {
     if (!src || typeof src !== "object")
         return base;
     const next = { ...base };
@@ -135,12 +214,31 @@ function applyAdvisorConfigSource(base, src) {
         if (normalized !== undefined)
             next.agentEffort = normalized;
     }
+    const disabledForModels = normalizeDisabledForModels(src.disabledForModels);
+    if (disabledForModels !== undefined) {
+        next.disabledForModels = disabledForModels;
+    }
+    // Benchmark paths merge per field so a plugin option can override one
+    // location while the other still falls back to the environment default.
+    const benchmarks = normalizeBenchmarks(src.benchmarks);
+    if (benchmarks !== undefined) {
+        next.benchmarks = { ...next.benchmarks, ...benchmarks };
+    }
     const timeout = toBoundedInt(src.timeoutMs ?? src.timeout_ms, 1);
     if (timeout !== undefined)
         next.timeoutMs = timeout;
     const cap = toBoundedInt(src.maxTranscriptChars ?? src.max_transcript_chars, 0);
     if (cap !== undefined)
         next.maxTranscriptChars = cap;
+    if (src.typesafe !== undefined) {
+        const normalized = normalizeTypeSafeOptions(src.typesafe);
+        if ("error" in normalized) {
+            throw new Error(normalized.error);
+        }
+        next.typesafeSource = normalized;
+    }
+    next.typesafe = resolveTypeSafeConfig(next.typesafeSource, env);
+    next.typesafeSettings = next.typesafe.settings;
     return next;
 }
 function envAdvisorConfigSource(env = process.env) {
@@ -151,14 +249,36 @@ function envAdvisorConfigSource(env = process.env) {
         timeoutMs: env.OCADVISOR_TIMEOUT_MS,
         maxTranscriptChars: env.OCADVISOR_MAX_TRANSCRIPT_CHARS,
         agentEffort: env.OCADVISOR_AGENT_EFFORT,
+        disabledForModels: env.OCADVISOR_DISABLED_FOR_MODELS,
+        benchmarks: env.OCADVISOR_BENCHMARKS_PATH === undefined &&
+            env.OCADVISOR_BENCHMARK_MAPPINGS_PATH === undefined &&
+            env.OCADVISOR_BENCHMARKS_MATCH_ANY_PROVIDER === undefined
+            ? undefined
+            : {
+                path: env.OCADVISOR_BENCHMARKS_PATH,
+                mappingsPath: env.OCADVISOR_BENCHMARK_MAPPINGS_PATH,
+                ...(env.OCADVISOR_BENCHMARKS_MATCH_ANY_PROVIDER !== undefined
+                    ? {
+                        matchAnyProvider: env.OCADVISOR_BENCHMARKS_MATCH_ANY_PROVIDER,
+                    }
+                    : {}),
+            },
     };
 }
 // Precedence (low to high): built-in defaults, environment variables,
 // plugin options from opencode.json.
 function resolveAdvisorConfig(options, env = process.env) {
-    let config = applyAdvisorConfigSource(DEFAULT_ADVISOR_CONFIG, envAdvisorConfigSource(env));
-    config = applyAdvisorConfigSource(config, options);
-    return config;
+    let config = applyAdvisorConfigSource(DEFAULT_ADVISOR_CONFIG, envAdvisorConfigSource(env), env);
+    config = applyAdvisorConfigSource(config, options, env);
+    // Resolved view always states the matching policy, so downstream code
+    // never has to invent the documented default.
+    return {
+        ...config,
+        benchmarks: {
+            ...config.benchmarks,
+            matchAnyProvider: config.benchmarks.matchAnyProvider ?? false,
+        },
+    };
 }
 const SYSTEM_BASE = `You are a senior advisor reviewing a coding agent's work. You have the full session transcript.
 Respond in 500-750 words with structured analysis and enumerated steps. Be direct and actionable.`;
@@ -174,15 +294,17 @@ You are a debugger. Analyze error patterns, stack traces, and failed attempts in
 };
 const TOOL_DESCRIPTION = `Consult a senior advisor model with your full session transcript — including parent sessions for subagents — for high-quality analysis.
 
-Use advisor selectively on substantial, non-trivial work. Straightforward tasks normally need no consultation.
+Use advisor when an independent perspective could improve the approach, help resolve a problem, or strengthen an implementation review.
+
+On substantial work, consider consulting before committing to an approach, when progress stalls, or before completing meaningful changes. Additional consultations are welcome as the work evolves — particularly when new evidence appears, the approach changes, or another concern needs review.
 
-- Normally make AT MOST ONE consultation per task, at the point where a second opinion has the most value: a consequential unresolved design decision (mode "plan"), a blocker after two substantially different attempts (mode "debug"), or a high-risk change with a specific unresolved correctness concern (mode "review"). Pick one stage, not all three.
-- mode "general": a second opinion that does not fit the above.
+Ask a concrete, focused question. Avoid repeating settled questions without new context. Straightforward tasks usually need no consultation.
 
 Rules:
 - Always pass a concrete "question" naming the decision or artifact under review.
-- A second consultation requires material new evidence, a distinct unresolved issue, or an explicit user request. Reconcile an advisor conflict with primary-source evidence via one "followup" call stating both sides.
+- Reconcile an advisor conflict with primary-source evidence via one "followup" call stating both sides.
 - Give the advice serious weight. A passing self-test alone is not counter-evidence; primary-source evidence (the file says X) is. Clear factual corrections do not need another confirmation call.
+- When TypeSafe screening is enabled, a clearly unnecessary consultation returns a skip notice instead of advice, and an omitted effort may be chosen for you.
 
 Args: "mode" (general, review, plan, debug), "trigger" (before_approach, stuck, pre_complete, followup, other), "question" (concrete question focusing the advisor).
 `;
@@ -195,7 +317,7 @@ function buildToolDescription(config = DEFAULT_ADVISOR_CONFIG) {
     return (TOOL_DESCRIPTION +
         `Optional "effort" (one of: ${config.agentEffort.join(", ")}): reasoning effort for this consultation; omit to use the configured variant.\n`);
 }
-const CHECKPOINT_INSTRUCTION = `[advisor] Use advisor selectively on substantial work: normally 0-1 consultations per task, at most one unless material new evidence, a distinct unresolved issue, or an explicit user request. Consult for a consequential undecided design (mode "plan"), a blocker after 2+ different attempts (mode "debug"), or a high-risk change with a specific correctness concern (mode "review"). Always pass a concrete question.`;
+const CHECKPOINT_INSTRUCTION = `[advisor] Consult advisor when an independent perspective would improve the approach, help resolve a problem, or strengthen review. Use useful checkpoints during substantial work; additional consultations are welcome when evidence, approach, or concerns change. Ask a concrete question and avoid repeating settled questions without new context.`;
 const ADVISOR_TRIGGERS = [
     "before_approach",
     "stuck",
@@ -240,8 +362,10 @@ function buildAdvisorInputSchema(config = DEFAULT_ADVISOR_CONFIG) {
         },
     };
 }
-function openDb() {
-    return new Database(DB_PATH, { readonly: true });
+function openDb(runtime) {
+    return new Database(runtime?.__advisorTest?.dbPath ?? DB_PATH, {
+        readonly: true,
+    });
 }
 function tableExists(db, name) {
     const row = db
@@ -267,6 +391,22 @@ function isFableModel(model) {
     const id = String(model.id || model.modelID || "").toLowerCase();
     return provider.includes("anthropic") && id.includes("fable");
 }
+function advisorDisabledReason(model, config) {
+    if (isFableModel(model)) {
+        return { outcome: "skipped_fable", message: FABLE_DISABLED };
+    }
+    const provider = model?.providerID || model?.provider;
+    const id = model?.id || model?.modelID;
+    if (!provider || !id)
+        return null;
+    const ref = `${provider}/${id}`;
+    if (!config.disabledForModels.includes(ref))
+        return null;
+    return {
+        outcome: "skipped_model",
+        message: `advisor is disabled (model opt-out): ${ref} is listed in disabledForModels.`,
+    };
+}
 function inferTrigger(mode, trigger) {
     if (trigger && ADVISOR_TRIGGERS.includes(trigger)) {
         return trigger;
@@ -405,6 +545,13 @@ function isAdvisorToolName(name) {
 function countPriorAdvisorCalls(db, sessionId) {
     const callIds = new Set();
     const modes = [];
+    const questions = [];
+    const record = (input) => {
+        modes.push(String(input?.mode || "general"));
+        if (typeof input?.question === "string" && input.question.trim()) {
+            questions.push(input.question);
+        }
+    };
     try {
         for (const sid of collectSessionChain(db, sessionId)) {
             if (tableExists(db, "session_message")) {
@@ -433,7 +580,7 @@ function countPriorAdvisorCalls(db, sessionId) {
                             const cid = String(block.id || block.callID || row.id);
                             if (!callIds.has(cid)) {
                                 callIds.add(cid);
-                                modes.push(String(state.input?.mode || "general"));
+                                record(state.input);
                             }
                         }
                         nested.forEach((call, index) => {
@@ -441,7 +588,7 @@ function countPriorAdvisorCalls(db, sessionId) {
                                 const cid = `${block.id || row.id}#${index}`;
                                 if (!callIds.has(cid)) {
                                     callIds.add(cid);
-                                    modes.push(String(call.input?.mode || "general"));
+                                    record(call.input);
                                 }
                             }
                         });
@@ -469,22 +616,88 @@ function countPriorAdvisorCalls(db, sessionId) {
                     if (!cid || callIds.has(cid))
                         continue;
                     callIds.add(cid);
-                    modes.push(String(block.state?.input?.mode || "general"));
+                    record(block.state?.input);
                 }
             }
         }
     }
     catch { }
-    return { count: callIds.size, modes };
+    return { count: callIds.size, modes, questions };
 }
-async function logAdvisorMetrics(metrics) {
+async function logAdvisorMetrics(runtime, metrics) {
     try {
-        await appendFile(METRICS_PATH, JSON.stringify(metrics) + "\n", "utf-8");
+        const path = runtime?.__advisorTest?.metricsPath ?? METRICS_PATH;
+        await appendFile(path, JSON.stringify(metrics) + "\n", "utf-8");
     }
     catch {
         // Metrics must never break the advisor call.
     }
 }
+// Flattens a gate decision into the additive metrics record. A bypassed gate
+// reports `bypass` so reports can separate bypass, skip, fallback, and
+// allowed proceed without inferring from other fields.
+function gateRecordFrom(decision) {
+    if (decision.status === "disabled") {
+        return {
+            status: "bypass",
+            reason: "disabled",
+            model: null,
+            neededProbability: null,
+            suggestedEffort: null,
+            effortConfidence: null,
+            effectiveEffort: null,
+            effortSource: null,
+            latencyMs: 0,
+            stateBytes: 0,
+            truncated: false,
+            inputTokens: null,
+            outputTokens: null,
+        };
+    }
+    const metrics = decision.metrics;
+    return {
+        status: decision.status,
+        reason: decision.reason,
+        model: metrics.model,
+        neededProbability: metrics.neededProbability,
+        suggestedEffort: metrics.suggestedEffort,
+        effortConfidence: metrics.effortConfidence,
+        effectiveEffort: decision.status === "proceed" ? decision.effectiveEffort : null,
+        effortSource: decision.status === "proceed" ? decision.effortSource : null,
+        latencyMs: metrics.latencyMs,
+        stateBytes: metrics.stateBytes,
+        truncated: metrics.truncated,
+        inputTokens: metrics.inputTokens,
+        outputTokens: metrics.outputTokens,
+    };
+}
+// Human-readable gate summary for the tool output. A bypassed gate contributes
+// nothing, so keyless or disabled installs keep the plain footer.
+export function gateSummary(gate) {
+    if (!gate || gate.status === "bypass")
+        return null;
+    const parts = [];
+    if (gate.neededProbability !== null) {
+        parts.push(`need=${gate.neededProbability.toFixed(2)}`);
+    }
+    if (gate.effectiveEffort) {
+        parts.push(gate.effortSource === "typesafe"
+            ? `effort=${gate.effectiveEffort} (gate)`
+            : `effort=${gate.effectiveEffort}`);
+    }
+    switch (gate.status) {
+        case "skip":
+            parts.push("decision=skip", gate.reason);
+            break;
+        case "fallback":
+            parts.push("decision=fallback", gate.reason);
+            break;
+        default:
+            parts.push("decision=proceed");
+            break;
+    }
+    return `gate: ${parts.join(", ")}`;
+}
 function getSession(db, sessionId) {
     return db
         .query("SELECT id, parent_id, title, directory FROM session WHERE id = ?")
@@ -759,6 +972,20 @@ function resolveAdvisorVariant(model, config = DEFAULT_ADVISOR_CONFIG, requested
     const ids = model.variants.map((variant) => variant?.id);
     return ids.includes(config.variant) ? config.variant : undefined;
 }
+// Effort levels the gate may choose: plugin-allowed candidates intersected
+// with the model's live variants. Unknown discovery yields no candidates,
+// which keeps the configured effort and omits automatic effort selection.
+function resolveSupportedEfforts(model, config) {
+    const allowed = config.agentEffort && config.agentEffort.length > 0
+        ? config.agentEffort
+        : null;
+    if (!allowed || !model || !Array.isArray(model.variants))
+        return [];
+    const variants = new Set(model.variants
+        .map((variant) => variant?.id)
+        .filter((id) => !!id));
+    return allowed.filter((effort) => variants.has(effort));
+}
 function hasAdvisorConnection(connection) {
     if (connection === null || connection === undefined)
         return false;
@@ -772,11 +999,50 @@ function hasAdvisorConnection(connection) {
     }
     return true;
 }
+// Discovery namespaces: the documented V2 `model`/`provider` domains win,
+// the legacy `catalog` namespace stays for older servers and fixtures.
+// Calls stay in method form so any receiver-bound implementation keeps
+// working.
+function discoveryModelApi(runtime) {
+    if (runtime.model && typeof runtime.model.list === "function") {
+        return runtime.model;
+    }
+    if (runtime.catalog?.model &&
+        typeof runtime.catalog.model.list === "function") {
+        return runtime.catalog.model;
+    }
+    return null;
+}
+function discoveryProviderApi(runtime) {
+    if (runtime.provider && typeof runtime.provider.get === "function") {
+        return runtime.provider;
+    }
+    if (runtime.catalog?.provider &&
+        typeof runtime.catalog.provider.get === "function") {
+        return runtime.catalog.provider;
+    }
+    return null;
+}
+// Shared by support checks and the effort gate; null means discovery is
+// unavailable or the configured model was not found.
+async function findAdvisorCatalogModel(runtime, config) {
+    const api = discoveryModelApi(runtime);
+    if (!api)
+        return null;
+    try {
+        const models = unwrapData((await api.list()));
+        return findAdvisorModel(models, config);
+    }
+    catch {
+        return null;
+    }
+}
 async function checkAdvisorSupport(runtime, config = DEFAULT_ADVISOR_CONFIG, requestedVariant) {
-    if (typeof runtime.catalog?.provider?.get === "function") {
+    const providerApi = discoveryProviderApi(runtime);
+    if (providerApi) {
         let provider = null;
         try {
-            provider = unwrapData((await runtime.catalog.provider.get({
+            provider = unwrapData((await providerApi.get({
                 providerID: config.provider,
             })));
         }
@@ -794,10 +1060,11 @@ async function checkAdvisorSupport(runtime, config = DEFAULT_ADVISOR_CONFIG, req
         }
     }
     let variant = requestedVariant ?? config.variant;
-    if (typeof runtime.catalog?.model?.list === "function") {
+    const modelApi = discoveryModelApi(runtime);
+    if (modelApi) {
         let models = null;
         try {
-            models = unwrapData((await runtime.catalog.model.list()));
+            models = unwrapData((await modelApi.list()));
         }
         catch (err) {
             return {
@@ -1025,10 +1292,25 @@ async function callAdvisor(opts) {
     const text = await enqueueAdvisor(() => withTimeout((async () => {
         const sessionId = await ensureAdvisorSession(runtime, support.variant, config);
         const request = { sessionID: sessionId, prompt };
-        const result = opts.signal
-            ? await generate(request, { signal: opts.signal })
-            : await generate(request);
-        const output = extractGeneratedText(result);
+        const startedAt = Date.now();
+        const run = async () => {
+            const result = opts.signal
+                ? await generate(request, { signal: opts.signal })
+                : await generate(request);
+            return extractGeneratedText(result);
+        };
+        // A generation can come back without text (transient provider
+        // behavior, e.g. a reasoning-only response with adaptive thinking).
+        // Retry once while most of the timeout budget remains; never retry
+        // after a caller cancellation.
+        let output = await run();
+        if (!output?.trim() && !opts.signal?.aborted) {
+            const elapsed = Date.now() - startedAt;
+            if (elapsed < config.timeoutMs / 2) {
+                console.log(`[advisor] empty generation; retrying once (session=${sessionId} elapsedMs=${elapsed})`);
+                output = await run();
+            }
+        }
         if (!output?.trim()) {
             throw new Error("Advisor returned an empty response.");
         }
@@ -1044,6 +1326,87 @@ async function callAdvisor(opts) {
         variant: support.variant,
     };
 }
+// Benchmark stores live for the process, keyed by resolved user paths (and
+// test seed overrides), so every consultation observes CLI refreshes
+// without re-reading unchanged files. Tests reset between cases.
+const benchmarkStores = new Map();
+function resetBenchmarkStores() {
+    benchmarkStores.clear();
+}
+function benchmarkStoreKey(snapshotPath, mappingsPath, matchAnyProvider, seedSnapshotPath, seedMappingsPath) {
+    return [
+        snapshotPath,
+        mappingsPath,
+        matchAnyProvider ? "any-provider" : "strict-provider",
+        seedSnapshotPath ?? "",
+        seedMappingsPath ?? "",
+    ].join("\n");
+}
+// Loads one consistent benchmark view and assembles gate evidence from it.
+// Any failure (bad paths, unreadable files, unexpected errors) yields null
+// and the consultation proceeds without benchmark enrichment.
+async function loadBenchmarkEvidence(runtime, config, requester, advisor) {
+    try {
+        const testOpts = runtime?.__advisorTest?.benchmarkStoreOptions;
+        const paths = resolveBenchmarkPaths(config.benchmarks, testOpts?.env ?? process.env);
+        if ("error" in paths)
+            return null;
+        const key = benchmarkStoreKey(paths.snapshotPath, paths.mappingsPath, config.benchmarks.matchAnyProvider ?? false, testOpts?.seedSnapshotPath, testOpts?.seedMappingsPath);
+        let store = benchmarkStores.get(key);
+        if (!store) {
+            store = await createBenchmarkStore({
+                snapshotPath: paths.snapshotPath,
+                mappingsPath: paths.mappingsPath,
+                seedSnapshotPath: testOpts?.seedSnapshotPath,
+                seedMappingsPath: testOpts?.seedMappingsPath,
+                fs: testOpts?.fs,
+                maxBytes: testOpts?.maxBytes,
+                matchAnyProvider: config.benchmarks.matchAnyProvider ?? false,
+            });
+            benchmarkStores.set(key, store);
+        }
+        const view = await store.view();
+        return {
+            view,
+            evidence: buildBenchmarkEvidence({ requester, advisor, view }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function summarizeBenchmarkEvidence(loaded, finalEffort) {
+    if (!loaded)
+        return undefined;
+    const { view, evidence } = loaded;
+    const { requester, advisor } = evidence.models;
+    const policy = advisor.policy;
+    const finalMatch = finalEffort === null
+        ? null
+        : view.matcher.match({
+            providerID: advisor.providerID,
+            modelID: advisor.modelID,
+            variant: finalEffort,
+        }).status;
+    return {
+        source: evidence.benchmarks.source,
+        contentHash: evidence.benchmarks.contentHash,
+        fetchedAt: evidence.benchmarks.fetchedAt,
+        hashVerified: evidence.benchmarks.hashVerified,
+        requester: requester.providerID && requester.modelID
+            ? `${requester.providerID}/${requester.modelID}${requester.variant ? `#${requester.variant}` : ""} (${requester.provenance})`
+            : null,
+        requesterMatch: evidence.benchmarks.requesterMatch.status,
+        advisorPolicy: policy.kind === "pinned"
+            ? `pinned:${policy.effort}`
+            : policy.kind === "candidates"
+                ? `candidates:${policy.candidates.join(",")}>${policy.fallback ?? "none"}`
+                : `fixed:${policy.effort ?? "none"}`,
+        advisorMatch: evidence.benchmarks.advisorDefaultMatch.status,
+        finalEffort,
+        finalMatch,
+    };
+}
 async function runAdvisor(opts) {
     const started = Date.now();
     const config = opts.config ?? DEFAULT_ADVISOR_CONFIG;
@@ -1052,7 +1415,7 @@ async function runAdvisor(opts) {
     const sessionId = opts.sessionId;
     const questionChars = opts.question?.length ?? 0;
     if (!sessionId) {
-        await logAdvisorMetrics({
+        await logAdvisorMetrics(opts.runtime, {
             ts: new Date().toISOString(),
             sessionId: null,
             callerModel: null,
@@ -1075,13 +1438,14 @@ async function runAdvisor(opts) {
     }
     let db = null;
     try {
-        db = openDb();
+        db = openDb(opts.runtime);
         const info = getSessionInfo(db, sessionId);
         const callerModel = callerLabel(info?.model ?? null);
         const callerAgent = opts.callerAgent || info?.agent || null;
         const directory = opts.callerDirectory || info?.directory || null;
-        if (isFableModel(info?.model)) {
-            await logAdvisorMetrics({
+        const disabled = advisorDisabledReason(info?.model, config);
+        if (disabled) {
+            await logAdvisorMetrics(opts.runtime, {
                 ts: new Date().toISOString(),
                 sessionId,
                 callerModel,
@@ -1091,7 +1455,7 @@ async function runAdvisor(opts) {
                 trigger,
                 questionChars,
                 effort: null,
-                outcome: "skipped_fable",
+                outcome: disabled.outcome,
                 errorType: null,
                 latencyMs: Date.now() - started,
                 inputTokens: null,
@@ -1100,12 +1464,12 @@ async function runAdvisor(opts) {
                 priorConsultations: 0,
                 via: "opencode-session",
             });
-            console.log(`[advisor] session=${sessionId} mode=${mode} outcome=skipped_fable (already Fable)`);
-            return FABLE_DISABLED;
+            console.log(`[advisor] session=${sessionId} mode=${mode} outcome=${disabled.outcome}`);
+            return disabled.message;
         }
         let transcript = buildTranscript(db, sessionId);
         if (!transcript?.trim()) {
-            await logAdvisorMetrics({
+            await logAdvisorMetrics(opts.runtime, {
                 ts: new Date().toISOString(),
                 sessionId,
                 callerModel,
@@ -1134,26 +1498,141 @@ async function runAdvisor(opts) {
                 "... (older transcript trimmed to fit maxTranscriptChars) ...\n\n" +
                     transcript.slice(-config.maxTranscriptChars);
         }
+        // Invocation-correct requester identity for benchmark matching: the
+        // model that produced this tool call, resolved after the early guards
+        // so skipped calls pay for no extra reads.
+        const requesterProfile = resolveRequesterProfile(db, {
+            sessionId,
+            messageID: opts.callerMessageID,
+            callID: opts.callerCallID,
+            sessionModel: info?.model ?? null,
+        });
         const prior = countPriorAdvisorCalls(db, sessionId);
         const priorNote = prior.count > 0
             ? `Note: this session chain already has ${prior.count} recorded advisor consultation(s) (modes: ${prior.modes.join(", ") || "unknown"}). Focus on what is new since then; do not repeat settled advice unless new evidence changes it.`
             : null;
         const systemPrompt = SYSTEM_PROMPTS[mode] || SYSTEM_PROMPTS.general;
         let requestedEffort;
+        let effectiveEffort;
+        let gateRecord;
+        let benchmarkLoaded = null;
         try {
             requestedEffort = resolveRequestedEffort(config, opts.effort);
+            // Optional TypeSafe preflight: one bounded request decides whether this
+            // consultation is worth the expensive generation and, when the caller
+            // did not pin an effort, which supported effort fits. Gate failures
+            // fall back to the ordinary behavior and never fail the call.
+            let gateDecision = null;
+            let advisorProfile = null;
+            if (config.typesafe.keyPresent && !config.typesafeSource.disabled) {
+                const catalogModel = await findAdvisorCatalogModel(opts.runtime, config);
+                const supportedEfforts = resolveSupportedEfforts(catalogModel, config);
+                advisorProfile = resolveAdvisorProfile({
+                    providerID: config.provider,
+                    modelID: config.model,
+                    requestedEffort,
+                    supportedEfforts,
+                    defaultEffort: requestedEffort ??
+                        resolveAdvisorVariant(catalogModel, config) ??
+                        null,
+                });
+                const gateSettings = config.typesafe.settings ?? TYPESAFE_DEFAULTS;
+                benchmarkLoaded = await loadBenchmarkEvidence(opts.runtime, config, requesterProfile, advisorProfile);
+                gateDecision = await runTypeSafeGate({
+                    state: buildDecisionState(db, sessionId, {
+                        question: opts.question ?? null,
+                        mode,
+                        trigger,
+                        explicitEffort: requestedEffort ?? null,
+                        caller: callerModel,
+                        directory,
+                        priorConsultations: prior.count,
+                        priorModes: prior.modes,
+                        priorQuestions: prior.questions,
+                        supportedEfforts,
+                        defaultEffort: requestedEffort ?? config.variant ?? null,
+                        maxStateBytes: gateSettings.maxStateBytes,
+                        models: benchmarkLoaded?.evidence.models ?? null,
+                        benchmarks: benchmarkLoaded?.evidence.benchmarks ?? null,
+                        formatMessage: formatV2Message,
+                    }),
+                    input: {
+                        mode,
+                        trigger,
+                        question: opts.question ?? null,
+                        explicitEffort: requestedEffort ?? null,
+                        supportedEfforts,
+                        defaultEffort: requestedEffort ?? config.variant ?? null,
+                    },
+                    settings: gateSettings,
+                    keyPresent: config.typesafe.keyPresent,
+                    client: opts.runtime?.__advisorTest?.gateClient,
+                    env: opts.runtime?.__advisorTest?.gateEnv,
+                    fetchImpl: opts.runtime?.__advisorTest?.gateFetch,
+                    signal: opts.signal,
+                });
+                gateRecord = gateRecordFrom(gateDecision);
+            }
+            // Profiles resolve for every consultation: with discovery the advisor
+            // policy reflects live variants, otherwise it fixes to the configured
+            // effort (or the caller's pin).
+            advisorProfile ??= resolveAdvisorProfile({
+                providerID: config.provider,
+                modelID: config.model,
+                requestedEffort,
+                supportedEfforts: [],
+                defaultEffort: config.variant ?? null,
+            });
+            opts.runtime?.__advisorTest?.profileSink?.({
+                requester: requesterProfile,
+                advisor: advisorProfile,
+            });
+            if (gateDecision?.status === "skip") {
+                const latencyMs = Date.now() - started;
+                await logAdvisorMetrics(opts.runtime, {
+                    ts: new Date().toISOString(),
+                    sessionId,
+                    callerModel,
+                    callerAgent,
+                    directory,
+                    mode,
+                    trigger,
+                    questionChars,
+                    effort: null,
+                    outcome: "skipped_typesafe",
+                    errorType: null,
+                    latencyMs,
+                    inputTokens: null,
+                    outputTokens: null,
+                    transcriptChars: transcript.length,
+                    priorConsultations: prior.count,
+                    via: "opencode-session",
+                    gate: gateRecord,
+                    benchmarks: summarizeBenchmarkEvidence(benchmarkLoaded, null),
+                });
+                console.log(`[advisor] session=${sessionId} mode=${mode} trigger=${trigger} outcome=skipped_typesafe needed=${gateDecision.metrics.neededProbability ?? "n/a"} latencyMs=${latencyMs}`);
+                const skipNote = gateSummary(gateRecord);
+                return (`advisor consultation skipped (typesafe): the request did not need an advisor at this point` +
+                    `${gateDecision.metrics.neededProbability !== null ? ` (need probability ${gateDecision.metrics.neededProbability.toFixed(2)})` : ""}. ` +
+                    `Ask again with a concrete unresolved question if the situation changes.` +
+                    (skipNote ? `\n_${skipNote}_` : ""));
+            }
+            effectiveEffort =
+                gateDecision?.status === "proceed" && gateDecision.effectiveEffort
+                    ? gateDecision.effectiveEffort
+                    : requestedEffort;
             const result = await callAdvisor({
                 runtime: opts.runtime,
                 systemPrompt,
                 transcript,
                 question: opts.question,
                 priorNote,
-                effort: requestedEffort,
+                effort: effectiveEffort,
                 signal: opts.signal,
                 config,
             });
             const latencyMs = Date.now() - started;
-            await logAdvisorMetrics({
+            await logAdvisorMetrics(opts.runtime, {
                 ts: new Date().toISOString(),
                 sessionId,
                 callerModel,
@@ -1171,16 +1650,20 @@ async function runAdvisor(opts) {
                 transcriptChars: transcript.length,
                 priorConsultations: prior.count,
                 via: "opencode-session",
+                gate: gateRecord,
+                benchmarks: summarizeBenchmarkEvidence(benchmarkLoaded, result.variant ?? effectiveEffort ?? requestedEffort ?? null),
             });
             console.log(`[advisor] session=${sessionId} mode=${mode} trigger=${trigger} outcome=advisor_response latencyMs=${latencyMs}`);
+            const gateNote = gateSummary(gateRecord);
             return (result.text +
-                `\n\n_advisor consultation #${prior.count + 1} in this session chain (trigger=${trigger})_`);
+                `\n\n_advisor consultation #${prior.count + 1} in this session chain (trigger=${trigger})_` +
+                (gateNote ? `\n_${gateNote}_` : ""));
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
             const errorType = classifyAdvisorError(message);
             const latencyMs = Date.now() - started;
-            await logAdvisorMetrics({
+            await logAdvisorMetrics(opts.runtime, {
                 ts: new Date().toISOString(),
                 sessionId,
                 callerModel,
@@ -1189,7 +1672,7 @@ async function runAdvisor(opts) {
                 mode,
                 trigger,
                 questionChars,
-                effort: requestedEffort ?? null,
+                effort: effectiveEffort ?? requestedEffort ?? null,
                 outcome: "error",
                 errorType,
                 latencyMs,
@@ -1198,6 +1681,8 @@ async function runAdvisor(opts) {
                 transcriptChars: transcript.length,
                 priorConsultations: prior.count,
                 via: "opencode-session",
+                gate: gateRecord,
+                benchmarks: summarizeBenchmarkEvidence(benchmarkLoaded, effectiveEffort ?? requestedEffort ?? null),
             });
             console.log(`[advisor] session=${sessionId} mode=${mode} trigger=${trigger} outcome=error errorType=${errorType} latencyMs=${latencyMs}`);
             throw new Error(`advisor failed (${errorType}): ${message}`);
@@ -1236,6 +1721,8 @@ export async function setupOcAdvisorV2(ctx) {
                         signal: context.abort,
                         callerAgent: context.agent,
                         callerDirectory: context.directory,
+                        callerMessageID: context.messageID,
+                        callerCallID: context.id,
                         config: advisorConfig,
                     });
                     return { content: text };
@@ -1251,15 +1738,17 @@ export async function setupOcAdvisorV2(ctx) {
                 return;
             // `event.tools` lists the direct tools available to this request.
             // OpenCode drops entries a hook adds for tools it did not register,
-            // so the hook can only hide the tool (Fable sessions), never add it.
-            // The checkpoint instruction is injected only when the tool is
-            // actually available, e.g. not when a permission rule removed it.
+            // so the hook can only hide the tool (Fable or opted-out sessions),
+            // never add it. The checkpoint instruction is injected only when
+            // the tool is actually available, e.g. not when a permission rule
+            // removed it.
+            const disabled = advisorDisabledReason(event.model, advisorConfig);
             let available = false;
             for (const key of Object.keys(event.tools)) {
                 if (!isAdvisorToolName(key)) {
                     continue;
                 }
-                if (isFableModel(event.model)) {
+                if (disabled) {
                     delete event.tools[key];
                 }
                 else {
@@ -1292,5 +1781,5 @@ export const OcAdvisorPluginV2 = plugin;
 export default plugin;
 // Named exports for unit tests (bun test). The plugin entrypoint is the
 // default export above.
-export { ADVISOR_TRIGGERS, CHECKPOINT_INSTRUCTION, DEFAULT_ADVISOR_CONFIG, TOOL_DESCRIPTION, buildAdvisorInputSchema, buildAdvisorPrompt, buildToolDescription, checkAdvisorSupport, classifyAdvisorError, ensureAdvisorSession, extractGeneratedText, findAdvisorModel, hasAdvisorConnection, inferTrigger, isAdvisorToolName, isFableModel, isProviderUsable, parseModelRef, resolveAdvisorConfig, resolveAdvisorVariant, resolveRequestedEffort, resetAdvisorSessionCache, unwrapData, withTimeout, };
+export { ADVISOR_TRIGGERS, CHECKPOINT_INSTRUCTION, DEFAULT_ADVISOR_CONFIG, TOOL_DESCRIPTION, buildAdvisorInputSchema, buildAdvisorPrompt, buildToolDescription, checkAdvisorSupport, classifyAdvisorError, ensureAdvisorSession, extractGeneratedText, findAdvisorModel, hasAdvisorConnection, advisorDisabledReason, inferTrigger, isAdvisorToolName, isFableModel, isProviderUsable, parseModelRef, resolveAdvisorConfig, resolveAdvisorVariant, resolveRequestedEffort, resolveSupportedEfforts, resetAdvisorSessionCache, resetBenchmarkStores, unwrapData, withTimeout, formatV2Message, runAdvisor, };
 //# sourceMappingURL=ocAdvisor.js.map