onto-mcp 0.4.13 → 0.4.14

package/dist/core-runtime/review/semantic-quality-gate.js

@@ -1,3 +1,15 @@
+/** The built-in code fixtures this gate can score — the value-level single
+ * source (the fixture-id type derives from it), mirroring
+ * SEMANTIC_QUALITY_GATE_CHECK_IDS below. FIXTURES is keyed by this type, so a new
+ * id here must ship a preset; the V2 scoring-completeness meta-test pins its
+ * scored set against THIS list at runtime, so a new fixture cannot enter the cert
+ * set with unproven (possibly stuck-on-pass) scoring. */
+export const SEMANTIC_QUALITY_GATE_FIXTURE_IDS = [
+    "review-pipeline-target-v1",
+    "retry-policy-target-v1",
+    "clean-target-v1",
+    "shared-root-target-v1",
+];
 /** The complete check-id universe this gate can emit — the value-level single
  * source (the check_id type derives from it). The review-cert/v2 evidence
  * contract pins its per-run check universe against THIS list, so a harness
@@ -17,6 +29,21 @@ export const SEMANTIC_QUALITY_GATE_CHECK_IDS = [
     "count_list_consistency",
     "grounding",
 ];
+/**
+ * Checks the gate OMITS for a clean-target fixture (expectsNoMaterialDefects):
+ * recall has nothing to recall, and grounding/actionability structurally fail
+ * on an empty material set (they require a material issue to ground / act on).
+ * These are declared N/A via the fixture's applicable_check_ids; the gate emits
+ * exactly the complementary applicable set. Kept as a module constant so the
+ * record-layer emission check (A-1b) can pin the same set.
+ */
+export const CLEAN_TARGET_EXCLUDED_CHECK_IDS = new Set([
+    "material_issue_recall",
+    "final_result_material_issue_recall",
+    "artifact_material_issue_recall",
+    "grounding",
+    "actionability",
+]);
 const DEFAULT_FIXTURE_ID = "review-pipeline-target-v1";
 const FIXTURES = {
     "review-pipeline-target-v1": {
@@ -73,6 +100,71 @@ const FIXTURES = {
         targetAnchor: "src/retry.ts",
         targetAnchorTerms: ["src/retry.ts", "retry.ts"],
     },
+    // v3 G1 clean-target (design §D1/§D3): ZERO material defects + one boundary
+    // decoy (an accepted-but-unread field whose defect status cannot be decided
+    // without caller/public-API evidence). materialTerms is empty (nothing to
+    // recall — accepted only because expectsNoMaterialDefects); recall/grounding/
+    // actionability are excluded from emission (CLEAN_TARGET_EXCLUDED). The control
+    // is the boundary decoy: yes-man → false_materiality_guard fails; empty silence
+    // → boundary_uncertainty_preservation MUST-preserve fails; correct silence
+    // (decoy preserved as non-material boundary context) passes.
+    "clean-target-v1": {
+        fixtureId: "clean-target-v1",
+        materialTerms: [],
+        expectedMaterialTruth: "no material defect (clean target)",
+        boundaryUncertaintyTerms: ["telemetry label", "debug export"],
+        boundaryContextTerms: [
+            "evidence gap",
+            "needs evidence",
+            "insufficient evidence",
+            "without caller",
+            "without public api",
+        ],
+        actionMaterialTerms: [],
+        actionRemediationTerms: [],
+        targetAnchor: "src/clean-target.ts",
+        targetAnchorTerms: ["src/clean-target.ts", "clean-target.ts"],
+        expectsNoMaterialDefects: true,
+        requiresBoundaryPreservation: true,
+    },
+    // v3 G2 shared-root (design §D1/§D3): ONE common root (rawFormat delegating to
+    // JSON.stringify, which returns undefined for top-level undefined) surfaces as
+    // TWO distinct defects (unstableFormat + alternateFormat both delegate to it),
+    // plus one INDEPENDENT defect (truncate off-by-one) and a lensId boundary decoy.
+    // The control is expectedSharedCauseAnchorPairs: the shared_cause branch of
+    // causal_relation_correctness no longer passes vacuously (`.every` over an empty
+    // relation set) — a valid shared_cause_candidate relation MUST connect the
+    // unstableFormat and alternate findings. All 12 checks are emitted (full
+    // universe): shared-root has real material defects, so the recall floor applies.
+    "shared-root-target-v1": {
+        fixtureId: "shared-root-target-v1",
+        materialTerms: ["unstableformat", "json.stringify", "undefined"],
+        expectedMaterialTruth: "unstableFormat + JSON.stringify + undefined",
+        boundaryUncertaintyTerms: ["lensid", "lens id", "lens ids", "lens identity"],
+        boundaryContextTerms: [
+            "evidence gap",
+            "needs evidence",
+            "insufficient evidence",
+            "low-confidence",
+            "unresolved",
+            "without caller",
+            "without public api",
+            "caller evidence",
+            "public api evidence",
+        ],
+        actionMaterialTerms: ["unstableformat", "json.stringify", "undefined"],
+        actionRemediationTerms: [
+            "return type",
+            "fallback",
+            "widen",
+            "guard",
+            "focused test",
+            "verify",
+        ],
+        targetAnchor: "src/shared-root.ts",
+        targetAnchorTerms: ["src/shared-root.ts", "shared-root.ts"],
+        expectedSharedCauseAnchorPairs: [[["unstableformat"], ["alternate"]]],
+    },
 };
 function semanticFixture(fixtureId) {
     const resolved = fixtureId ?? DEFAULT_FIXTURE_ID;
@@ -81,6 +173,13 @@ function semanticFixture(fixtureId) {
     }
     return FIXTURES[resolved];
 }
+/** SSOT accessor for a built-in fixture's pinned expectation preset (design §D3 —
+ * Phase A fixtures are code-presets). Returns a deep copy so callers cannot mutate
+ * the shared preset; tests and the cert manifest read the SAME source, so an
+ * injected copy can never drift from what the gate actually evaluates. */
+export function semanticQualityFixturePreset(fixtureId) {
+    return structuredClone(semanticFixture(fixtureId));
+}
 function records(value) {
     return Array.isArray(value)
         ? value.filter((item) => typeof item === "object" && item !== null)
@@ -151,6 +250,24 @@ function validCausalPath(value) {
             nonEmptyString(step.claim) &&
             nonEmptyStringArray(step.evidence_refs));
 }
+/**
+ * A shared_cause_candidate relation is internally consistent: it carries a
+ * shared_cause block whose from/to cause refs are owned by the relation's own
+ * endpoint findings. The single authority for shared-cause validity — consumed
+ * both by causal_relation_correctness's negative sweep (every relation must be
+ * valid) and by its positive anchor-pair existence requirement (v3 G2).
+ */
+function validSharedCauseRelation(relation, causeOwnerById) {
+    const sharedCause = record(relation.shared_cause);
+    const fromFindingId = typeof relation.from_finding_id === "string" ? relation.from_finding_id : "";
+    const toFindingId = typeof relation.to_finding_id === "string" ? relation.to_finding_id : "";
+    return (sharedCause !== null &&
+        nonEmptyString(sharedCause.cause_claim) &&
+        nonEmptyString(sharedCause.from_cause_ref) &&
+        nonEmptyString(sharedCause.to_cause_ref) &&
+        causeOwnerById.get(sharedCause.from_cause_ref) === fromFindingId &&
+        causeOwnerById.get(sharedCause.to_cause_ref) === toFindingId);
+}
 /**
  * Whether two findings inside one issue are connected through
  * same_root_candidate relations cited in that issue's relation_refs — the
@@ -313,28 +430,53 @@ function issueArtifactChecks(artifacts, declaredNonMaterialFindingCount, nonMate
         `preserved_non_material_ids=${nonMaterialPreservationIds.join(",") || "none"}`,
         "non-material findings must preserve target-specific boundary uncertainty and remain outside relation coverage",
     ]);
+    // v3 G2: when the fixture declares anchor pairs, each pair MUST be connected
+    // by a valid shared_cause_candidate relation between findings anchored to the
+    // two term-groups — closing the `.every`-vacuous pass that lets a missing
+    // relation through. A finding is anchored to a group when its text contains
+    // every term in the group (terms are lowercased to match normalizedText).
+    const anchorPairs = fixture.expectedSharedCauseAnchorPairs ?? [];
+    const findingById = new Map();
+    for (const finding of findings) {
+        if (typeof finding.finding_id === "string") {
+            findingById.set(finding.finding_id, finding);
+        }
+    }
+    const findingMatchesAnchorGroup = (finding, group) => {
+        if (!finding)
+            return false;
+        const text = normalizedText(finding);
+        return group.every((term) => text.includes(term.toLowerCase()));
+    };
+    const anchorPairsSatisfied = anchorPairs.every(([groupA, groupB]) => relationRows.some((relation) => {
+        if (relation.relation !== "shared_cause_candidate")
+            return false;
+        // G2 requires TWO DISTINCT surface defects sharing a root — a self-relation
+        // (from === to) on one finding that happens to match both groups is a
+        // degenerate loop, not a genuine cross-defect link.
+        if (relation.from_finding_id === relation.to_finding_id)
+            return false;
+        if (!validSharedCauseRelation(relation, causeOwnerById))
+            return false;
+        const fromFinding = typeof relation.from_finding_id === "string"
+            ? findingById.get(relation.from_finding_id)
+            : undefined;
+        const toFinding = typeof relation.to_finding_id === "string"
+            ? findingById.get(relation.to_finding_id)
+            : undefined;
+        return ((findingMatchesAnchorGroup(fromFinding, groupA) &&
+            findingMatchesAnchorGroup(toFinding, groupB)) ||
+            (findingMatchesAnchorGroup(fromFinding, groupB) &&
+                findingMatchesAnchorGroup(toFinding, groupA)));
+    }));
     const causalRelationCorrectness = check("causal_relation_correctness", materialFindingIds.every((findingId) => relationCoveredIds.has(findingId)) &&
-        relationRows.every((relation) => {
-            if (relation.relation !== "shared_cause_candidate")
-                return true;
-            const sharedCause = record(relation.shared_cause);
-            const fromFindingId = typeof relation.from_finding_id === "string"
-                ? relation.from_finding_id
-                : "";
-            const toFindingId = typeof relation.to_finding_id === "string"
-                ? relation.to_finding_id
-                : "";
-            return (sharedCause !== null &&
-                nonEmptyString(sharedCause.cause_claim) &&
-                nonEmptyString(sharedCause.from_cause_ref) &&
-                nonEmptyString(sharedCause.to_cause_ref) &&
-                causeOwnerById.get(sharedCause.from_cause_ref) ===
-                    fromFindingId &&
-                causeOwnerById.get(sharedCause.to_cause_ref) === toFindingId);
-        }), [
+        relationRows.every((relation) => relation.relation !== "shared_cause_candidate" ||
+            validSharedCauseRelation(relation, causeOwnerById)) &&
+        anchorPairsSatisfied, [
         `material_finding_ids=${materialFindingIds.join(",") || "none"}`,
         `relation_covered_ids=${[...relationCoveredIds].join(",") || "none"}`,
         `shared_cause_relation_ids=${sharedCauseRelationIds.join(",") || "none"}`,
+        `expected_shared_cause_anchor_pairs=${anchorPairs.length} satisfied=${anchorPairsSatisfied}`,
     ]);
     const dependencyPreservation = check("issue_dependency_preservation", relationRows.every((relation) => {
         if (relation.relation !== "shared_cause_candidate")
@@ -420,20 +562,41 @@ export function evaluateReviewPipelineSemanticQualityGate(args) {
     const fixture = args.expectations ?? semanticFixture(args.fixtureId);
     if (fixture.materialTerms.length === 0) {
         // textContainsAll over an empty list is vacuously true, so the material
-        // recall checks would prove nothing — fail loud instead.
-        throw new Error("SemanticQualityExpectations.materialTerms must not be empty");
+        // recall checks would prove nothing — fail loud UNLESS this is a
+        // clean-target fixture, where there is genuinely nothing to recall and the
+        // recall checks are excluded from emission (see CLEAN_TARGET_EXCLUDED).
+        if (!fixture.expectsNoMaterialDefects) {
+            throw new Error("SemanticQualityExpectations.materialTerms must not be empty");
+        }
     }
-    // 빈 문자열 term/alternate는 text.includes("")가 항상 참이라 해당 entry를
-    // 공허 충족시킨다 — 게이트 진입에서 fail loud.
-    for (const term of fixture.materialTerms) {
-        const alternates = Array.isArray(term) ? term : [term];
-        if (alternates.length === 0 ||
-            alternates.some((alternate) => alternate.trim().length === 0)) {
-            throw new Error("SemanticQualityExpectations.materialTerms entries must be non-empty strings or non-empty groups of non-empty strings");
+    else {
+        // 빈 문자열 term/alternate는 text.includes("")가 항상 참이라 해당 entry를
+        // 공허 충족시킨다 — 게이트 진입에서 fail loud.
+        for (const term of fixture.materialTerms) {
+            const alternates = Array.isArray(term) ? term : [term];
+            if (alternates.length === 0 ||
+                alternates.some((alternate) => alternate.trim().length === 0)) {
+                throw new Error("SemanticQualityExpectations.materialTerms entries must be non-empty strings or non-empty groups of non-empty strings");
+            }
         }
     }
+    // A clean-target's whole control is the boundary decoy: with no material
+    // defect the recall floor cannot catch silence, so distinguishing correct
+    // silence from lazy empty silence REQUIRES MUST-preserve. A clean-target that
+    // forgets requiresBoundaryPreservation would let empty silence pass vacuously
+    // — fail loud on the misconfiguration rather than certify a broken control.
+    if (fixture.expectsNoMaterialDefects && !fixture.requiresBoundaryPreservation) {
+        throw new Error("SemanticQualityExpectations.expectsNoMaterialDefects requires requiresBoundaryPreservation — without the boundary decoy control, empty silence passes vacuously");
+    }
     const summary = args.reviewRecord.result_classification_summary ?? null;
     const materialIssues = records(summary?.material_issues);
+    // Clean-target (v3 G1): material promotion must be caught on BOTH surfaces —
+    // the summary AND the finding-ledger authority. false_materiality_guard reads
+    // the summary; this counts artifact-ledger material findings so a fabricated
+    // material finding injected only into the ledger cannot slip past the guard.
+    const artifactMaterialFindingCount = fixture.expectsNoMaterialDefects
+        ? recordArray(record(args.issueArtifacts?.findingLedger)?.findings).filter((finding) => ["blocker", "high", "medium"].includes(String(finding.severity))).length
+        : 0;
     const nonMaterialFindings = records(summary?.non_material_findings);
     const actionCandidates = records(summary?.action_candidates);
     const materialText = normalizedText(materialIssues);
@@ -469,13 +632,27 @@ export function evaluateReviewPipelineSemanticQualityGate(args) {
             : `Final Review Result chars=${finalReviewResult.length}`,
         `expected final explanation to preserve ${fixture.expectedMaterialTruth}`,
     ]);
-    const falseMaterialityGuard = check("false_materiality_guard", !materialBoundarySensitiveFalsePositive &&
+    const falseMaterialityGuard = check("false_materiality_guard", 
+    // Clean-target (v3 G1): the target has zero material defects, so ANY
+    // admitted material issue is a false positive — on EITHER surface. A yes-man
+    // that promotes a fabricated issue fails here whether it lands in the summary
+    // (materialIssues) or only in the finding-ledger authority
+    // (artifactMaterialFindingCount), not just the boundary case the base branch
+    // catches.
+    (!fixture.expectsNoMaterialDefects ||
+        (materialIssues.length === 0 && artifactMaterialFindingCount === 0)) &&
+        !materialBoundarySensitiveFalsePositive &&
         (!falseMaterialityCandidateObserved ||
             (textContainsAny(preservedBoundaryText, fixture.boundaryUncertaintyTerms) &&
                 textContainsAny(preservedBoundaryText, fixture.boundaryContextTerms))), [
         `boundary-sensitive uncertainty terms must be disclosed with boundary context when they are not admitted material issues: ${fixture.boundaryUncertaintyTerms.join(", ")}`,
         `non_material_finding_count=${nonMaterialFindings.length}`,
         `boundary_notes_chars=${boundaryNotes?.length ?? 0}`,
+        ...(fixture.expectsNoMaterialDefects
+            ? [
+                `clean-target: admitted material_issue_count=${materialIssues.length}, artifact_material_finding_count=${artifactMaterialFindingCount} (both must be 0)`,
+            ]
+            : []),
     ]);
     // Boundary uncertainty's preservation AUTHORITY is the finding-ledger
     // (non-material findings), not the final Boundary Notes projection. A model
@@ -488,10 +665,19 @@ export function evaluateReviewPipelineSemanticQualityGate(args) {
     // false_materiality_guard, which checks the ORTHOGONAL axis: the decoy was not
     // mis-promoted to a material issue. (A decoy surfaced only in the final note but
     // absent from the authority still fails here — authority is where it must live.)
-    const boundaryUncertainty = check("boundary_uncertainty_preservation", !falseMaterialityCandidateObserved ||
-        containsBoundarySensitiveUncertainty(nonMaterialText, fixture), [
+    const boundaryUncertainty = check("boundary_uncertainty_preservation", 
+    // Clean-target (v3 G1): the boundary decoy MUST be preserved — an empty,
+    // lazy review that observes nothing no longer passes the vacuous first
+    // clause. Otherwise the base rule stands: preserve only what was observed.
+    fixture.requiresBoundaryPreservation
+        ? containsBoundarySensitiveUncertainty(nonMaterialText, fixture)
+        : !falseMaterialityCandidateObserved ||
+            containsBoundarySensitiveUncertainty(nonMaterialText, fixture), [
         `non_material_boundary_chars=${nonMaterialText.length}`,
         `expected boundary uncertainty (${fixture.boundaryUncertaintyTerms.join(", ")}) preserved in the finding-ledger authority (non-material findings)`,
+        ...(fixture.requiresBoundaryPreservation
+            ? ["clean-target: boundary decoy MUST be preserved (empty silence fails)"]
+            : []),
     ]);
     const materialActionRefs = new Set(materialIssues.flatMap((issue) => strings(issue.action_candidates)));
     for (const item of actionCandidates) {
@@ -530,12 +716,21 @@ export function evaluateReviewPipelineSemanticQualityGate(args) {
         actionability,
         grounding,
     ];
+    // Clean-target (v3 G1): emit only the applicable set — the recall/grounding/
+    // actionability checks are N/A with no material defect and would structurally
+    // fail on an empty material set. The record layer's per-fixture emission pin
+    // (A-1b) expects exactly this reduced set for such a fixture.
+    const emittedChecks = fixture.expectsNoMaterialDefects
+        ? checks.filter((item) => !CLEAN_TARGET_EXCLUDED_CHECK_IDS.has(item.check_id))
+        : checks;
     return {
-        status: checks.every((item) => item.status === "passed") ? "passed" : "failed",
+        status: emittedChecks.every((item) => item.status === "passed")
+            ? "passed"
+            : "failed",
         fixture_id: fixture.fixtureId,
         scope: "fixture_specific",
         fixture_target_anchor: fixture.targetAnchor,
         applicability: "real_model_only",
-        checks,
+        checks: emittedChecks,
     };
 }

package/dist/mcp/server.js

@@ -18,6 +18,32 @@ const MCP_COMPACT_SIGNAL_MAX_CHARS = 360;
 const MCP_COMPACT_ID_MAX_CHARS = 120;
 const reviewApi = createOntoReviewCoreApi();
 const reconstructApi = createOntoReconstructCoreApi();
+// Shared advertised JSON-schema fragment for the per-call `llmOverride` property.
+// Kept in sync with PerCallLlmOverrideSchema (settings-chain); tool-surface.test.ts
+// asserts both the zod and advertised surfaces carry it.
+const LLM_OVERRIDE_PROPERTY_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        provider: {
+            type: "string",
+            enum: ["openai", "anthropic", "grok", "lmstudio"],
+        },
+        auth: { type: "string", enum: ["api_key", "oauth", "local"] },
+        model: { type: "string" },
+        effort: { type: "string" },
+        service_tier: { type: "string" },
+    },
+    // A provider switch needs an explicit model (the switched-in provider has no
+    // default model to inherit). The zod boundary enforces this; declaring it here
+    // too means a client reading tools/list sees the same contract instead of
+    // discovering it from a rejection. Both draft-07 (`if`/`then`) and 2019-09+
+    // (`dependentRequired`) spellings are supplied so either validator honors it.
+    if: { required: ["provider"] },
+    then: { required: ["model"] },
+    dependentRequired: { provider: ["model"] },
+    description: "Optional per-call LLM override: an ephemeral settings-llm overlay applied to this invocation's dispatch seats (provider switch replaces the actor block; a partial block field-overlays same-provider). Transport (base_url/api_key_env/timeout) stays settings-owned. Omit → settings unchanged (byte-identical default-off).",
+};
 const REVIEW_INPUT_SCHEMA = {
     type: "object",
     additionalProperties: false,
@@ -97,6 +123,7 @@ const REVIEW_INPUT_SCHEMA = {
             type: "number",
             description: "Optional synchronous wait budget in milliseconds. When exceeded after session planning, onto_review returns a running handle and background execution continues; recover via onto_review_read(latest=true). The default is profile-aware (simple 45s, full 25s; override with env ONTO_MCP_REVIEW_RETURN_RUNNING_AFTER_MS or ..._SIMPLE) — most core-axis reviews exceed any host-safe window and return a handle.",
         },
+        llmOverride: LLM_OVERRIDE_PROPERTY_SCHEMA,
     },
 };
 const SESSION_INPUT_SCHEMA = {
@@ -357,10 +384,6 @@ const RECONSTRUCT_INPUT_SCHEMA = {
             enum: ["direct_call"],
             description: "Explicit confirmation provider realization. direct_call uses configured llm provider.",
         },
-        llmEffort: {
-            type: "string",
-            description: "Optional reasoning-effort pin applied to both reconstruct actors (live only; mock ignores it).",
-        },
         judgeLlmEffort: {
             type: "string",
             description: "Opt-in: run the answer-support judge at a different reasoning effort than the semantic author (live only). Reduces same-model rubber-stamping.",
@@ -369,6 +392,7 @@ const RECONSTRUCT_INPUT_SCHEMA = {
             type: "string",
             description: "Opt-in: swap the answer-support judge MODEL (on the semantic author's provider; live only). An unsupported model degrades to the author model (INV-MODEL-1); a degrade is recorded as a runtime status note.",
         },
+        llmOverride: LLM_OVERRIDE_PROPERTY_SCHEMA,
     },
 };
 const RECONSTRUCT_SESSION_INPUT_SCHEMA = {
@@ -526,12 +550,124 @@ function resolveToolProfile() {
         ? "simple"
         : "full";
 }
-export function advertisedToolDefinitions() {
-    if (resolveToolProfile() !== "simple") {
-        return TOOL_DEFINITIONS;
-    }
-    const simple = new Set(OntoSimpleProfileToolNames);
-    return TOOL_DEFINITIONS.filter((tool) => simple.has(tool.name));
+// Published MCP protocol revisions onto's response shapes conform to, newest
+// first. onto emits additive fields from later revisions — tool annotations
+// (2025-03-26), structuredContent/outputSchema (2025-06-18) — and does not use
+// JSON-RPC batching (removed in 2025-06-18), so it honestly supports the whole
+// range. The optional 2025-11-25 server features (icons, tasks, elicitation)
+// are not advertised and not required for conformance. Negotiation echoes the
+// client's requested version when supported; otherwise it returns the latest.
+//
+// Scope: this negotiator governs the `initialize` handshake used by every stable
+// revision through 2025-11-25. The in-progress draft (RC 2026-07-28) removes
+// `initialize` for a stateless model (per-request `_meta` version +
+// `server/discover`); it is intentionally out of scope here. onto degrades
+// gracefully with RC-aware clients — an unknown `server/discover` returns -32601
+// (Method not found), so the client falls back to this handshake — a path locked
+// by protocol-version.test.ts. Full RC support is a separate, deferred workstream
+// (the draft is not yet ready for consumption).
+export const SUPPORTED_PROTOCOL_VERSIONS = [
+    "2025-11-25",
+    "2025-06-18",
+    "2025-03-26",
+    "2024-11-05",
+];
+export const LATEST_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[0];
+// The floor is the oldest supported revision — the version a client that never
+// completed negotiation is treated as, so it receives the pre-2025 tool surface.
+const FLOOR_PROTOCOL_VERSION = SUPPORTED_PROTOCOL_VERSIONS[SUPPORTED_PROTOCOL_VERSIONS.length - 1];
+export function negotiateProtocolVersion(requested) {
+    return typeof requested === "string" &&
+        SUPPORTED_PROTOCOL_VERSIONS.includes(requested)
+        ? requested
+        : LATEST_PROTOCOL_VERSION;
+}
+// Connection-scoped: a stdio server serves one client per process, so the
+// version negotiated at `initialize` is remembered here and gates which
+// additive tool-definition fields tools/list may emit. It starts at the floor
+// so a client that skips negotiation gets the conservative legacy surface.
+let negotiatedProtocolVersion = FLOOR_PROTOCOL_VERSION;
+export function setNegotiatedProtocolVersion(version) {
+    negotiatedProtocolVersion = version;
+}
+// Revisions that introduced each additive tool-definition field. onto emits a
+// field only to clients that negotiated its revision (or later), so an older
+// client — including an older Claude Desktop that negotiates 2024-11-05 —
+// receives byte-identical pre-2025 tool definitions. YYYY-MM-DD strings compare
+// chronologically under lexical ordering.
+const TOOL_ANNOTATIONS_SINCE = "2025-03-26";
+const TOOL_OUTPUT_SCHEMA_SINCE = "2025-06-18";
+// Advisory MCP tool hints (introduced 2025-03-26, carried unchanged into the
+// draft/RC). onto confines every write to `.onto/` and never destroys user
+// sources, so destructiveHint is false throughout. readOnlyHint marks the pure
+// read/list tools; openWorldHint marks the tools that themselves dispatch to
+// external LLM providers (they spend tokens and are non-deterministic). Keyed by
+// OntoToolName for compile-time completeness — a new advertised tool must
+// declare its hints here or the build fails.
+const TOOL_ANNOTATIONS = {
+    onto_review: { title: "Run review", readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    onto_prepare_review: { title: "Prepare review session", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    onto_review_continue: { title: "Resume review", readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    onto_review_round: { title: "Get review round (host-orchestrated)", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    onto_review_advance: { title: "Advance review round", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    onto_review_cancel: { title: "Cancel review", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    onto_review_read: { title: "Read review session", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    onto_observe_source: { title: "Observe reconstruct sources", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    onto_validate_reconstruct_directive: { title: "Validate reconstruct directive", readOnlyHint: false, destructiveHint: false, openWorldHint: false },
+    onto_reconstruct: { title: "Reconstruct ontology seed", readOnlyHint: false, destructiveHint: false, openWorldHint: true },
+    onto_reconstruct_read: { title: "Read reconstruct session", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+    onto_list: { title: "List registry", readOnlyHint: true, destructiveHint: false, openWorldHint: false },
+};
+// Declared result schema for tools whose structuredContent shape is stable
+// enough to pin without brittleness. MCP (2025-06-18+, loosened in the draft/RC)
+// requires a tool that declares outputSchema to return conforming
+// structuredContent, so this is intentionally selective. onto_list's three
+// per-kind envelopes are typed and stable; the read/record tools vary by
+// projectionLevel and are deliberately deferred. Parity with the real output is
+// enforced by tool-surface.behavior.test.ts against these declared shapes.
+const TOOL_OUTPUT_SCHEMAS = {
+    onto_list: {
+        type: "object",
+        anyOf: [
+            {
+                required: ["full", "coreAxis"],
+                properties: {
+                    full: { type: "array", items: { type: "string" } },
+                    coreAxis: { type: "array", items: { type: "string" } },
+                },
+            },
+            {
+                required: ["domains"],
+                properties: { domains: { type: "array", items: { type: "string" } } },
+            },
+            {
+                required: ["sourceProfiles"],
+                properties: { sourceProfiles: { type: "array" } },
+            },
+        ],
+    },
+};
+export function advertisedToolDefinitions(protocolVersion = negotiatedProtocolVersion) {
+    const base = resolveToolProfile() === "simple"
+        ? TOOL_DEFINITIONS.filter((tool) => new Set(OntoSimpleProfileToolNames).has(tool.name))
+        : TOOL_DEFINITIONS;
+    const withAnnotations = protocolVersion >= TOOL_ANNOTATIONS_SINCE;
+    const withOutputSchema = protocolVersion >= TOOL_OUTPUT_SCHEMA_SINCE;
+    // Merge additive fields onto a copy — TOOL_DEFINITIONS stays the pristine
+    // dispatch source; only tools/list carries them, and only for clients that
+    // negotiated the revision that introduced each field. A client below both
+    // thresholds receives the definition unchanged.
+    return base.map((tool) => {
+        const merged = { ...tool };
+        if (withAnnotations)
+            merged.annotations = TOOL_ANNOTATIONS[tool.name];
+        if (withOutputSchema) {
+            const outputSchema = TOOL_OUTPUT_SCHEMAS[tool.name];
+            if (outputSchema !== undefined)
+                merged.outputSchema = outputSchema;
+        }
+        return merged;
+    });
 }
 export const USAGE_GUIDE = `# Using onto via MCP
 
@@ -611,6 +747,24 @@ Discover material profiles with \`onto_list\` (kind="source_profiles").
   they are presentation guidance, not operating instructions.
 - onto writes only under \`{projectRoot}/.onto/\`; it never mutates your sources.
 `;
+// Server-level orientation returned in the `initialize` result so a host LLM
+// gets the big picture on connect. Deliberately a short summary plus a pointer:
+// the durable, detailed authority is the `onto://usage` resource, which is why
+// this stays initialize-era-only. The draft/RC drops the initialize handshake,
+// so orientation there falls back to that same resource — no detail is stranded
+// in this field.
+const SERVER_INSTRUCTIONS = [
+    "onto is an MCP-native ontology-as-code runtime with two paths: `review`",
+    "(structured, context-isolated multi-lens review of a target) and `reconstruct`",
+    "(derive a bounded, actionable ontology seed from real sources). The runtime",
+    "owns every artifact and validation gate; tool results put structured data in",
+    "structuredContent and carry llmPresentation prompts for user-facing",
+    "explanation. Both paths execute real LLM work and FAIL LOUD without a provider",
+    "configured in .onto/settings.json (or ~/.onto/settings.json). review is",
+    "long-running — poll onto_review_read until it is no longer running. Read the",
+    "`onto://usage` resource for provider setup and the full workflows before first",
+    "use.",
+].join(" ");
 const RESOURCE_DEFINITIONS = [
     {
         uri: "onto://usage",
@@ -697,6 +851,9 @@ function toReviewRequest(input) {
         ...(parsed.confirmValueAlignment !== undefined
             ? { confirmValueAlignment: parsed.confirmValueAlignment }
             : {}),
+        ...(parsed.llmOverride !== undefined
+            ? { llmOverride: parsed.llmOverride }
+            : {}),
     };
     return request;
 }
@@ -1537,9 +1694,9 @@ export async function callTool(name, args, options = {}) {
                     ...(parsed.resumeMode !== undefined ? { resumeMode: parsed.resumeMode } : {}),
                     semanticAuthorRealization: parsed.semanticAuthorRealization,
                     confirmationProviderRealization: parsed.confirmationProviderRealization,
-                    ...(parsed.llmEffort !== undefined ? { llmEffort: parsed.llmEffort } : {}),
                     ...(parsed.judgeLlmEffort !== undefined ? { judgeLlmEffort: parsed.judgeLlmEffort } : {}),
                     ...(parsed.judgeModel !== undefined ? { judgeModel: parsed.judgeModel } : {}),
+                    ...(parsed.llmOverride !== undefined ? { llmOverride: parsed.llmOverride } : {}),
                     ...(sessionRoot ? { sessionRoot } : {}),
                     ...(profilesRoot ? { profilesRoot } : {}),
                     ...(filesystemAllowedRoots ? { filesystemAllowedRoots } : {}),
@@ -1597,20 +1754,26 @@ function jsonRpcError(id, code, message) {
         error: { code, message },
     };
 }
-async function handleRequest(message) {
+export async function handleRequest(message) {
     if (!message.id && message.method?.startsWith("notifications/")) {
         return null;
     }
     switch (message.method) {
-        case "initialize":
+        case "initialize": {
+            const params = message.params;
+            const negotiated = negotiateProtocolVersion(params?.protocolVersion);
+            // Remember it so tools/list gates its additive fields on the same version.
+            setNegotiatedProtocolVersion(negotiated);
             return jsonRpcResult(message.id, {
-                protocolVersion: "2024-11-05",
+                protocolVersion: negotiated,
                 capabilities: { tools: {}, resources: {}, prompts: {} },
                 serverInfo: {
                     name: "onto-mcp",
                     version: await readPackageVersion(),
                 },
+                instructions: SERVER_INSTRUCTIONS,
             });
+        }
         case "ping":
             return jsonRpcResult(message.id, {});
         case "tools/list":