open-multi-agent-kit 0.79.3 → 0.80.0

package/dist/runtime/structured-compaction.d.ts

@@ -0,0 +1,107 @@
+import type { ContextCapsule } from "./context-capsule.js";
+export interface StructuredCompactionContractV1 {
+    readonly schemaVersion: "omk.structured-compaction.v1";
+    readonly requiredSections: readonly string[];
+    readonly minTaskPrefixChars: number;
+    readonly safetyMarkers: readonly string[];
+}
+export interface StructuredCompactionContractV2 {
+    readonly schemaVersion: "omk.structured-compaction.v2";
+    readonly node: {
+        readonly id: string;
+        readonly role: string;
+    };
+    readonly routing: {
+        readonly provider: string;
+        readonly risk: string;
+        readonly sandboxMode: string;
+        readonly readOnly: boolean;
+        readonly approvalPolicy: string;
+    };
+    readonly evidence: {
+        readonly required: readonly {
+            readonly gate: string;
+            readonly ref?: string;
+        }[];
+    };
+    readonly capabilities: readonly string[];
+    readonly safety: {
+        readonly evidenceRequired: boolean;
+        readonly preserve: readonly string[];
+    };
+}
+export type StructuredCompactionContract = StructuredCompactionContractV1 | StructuredCompactionContractV2;
+export interface StructuredCompactionValidationResult {
+    readonly ok: boolean;
+    readonly missing: readonly string[];
+    readonly contract: StructuredCompactionContract;
+}
+export interface StructuredCompactionBuildOptions {
+    /** Approximate target budget for the generated fallback text. */
+    readonly maxTokens?: number;
+    /** Apply secret redaction to all non-contract free text. Default true. */
+    readonly redact?: boolean;
+    readonly maxMemoryFacts?: number;
+    readonly maxDependencySummaries?: number;
+    readonly estimator?: TokenEstimationOptions;
+}
+export interface TokenEstimationCalibration {
+    readonly multiplier?: number;
+    readonly bias?: number;
+}
+export interface TokenEstimationOptions {
+    readonly provider?: string;
+    readonly model?: string;
+    readonly calibration?: TokenEstimationCalibration;
+}
+export interface CompactionQualityInput {
+    readonly applied: boolean;
+    readonly validated: boolean;
+    readonly beforeTokens?: number | null;
+    readonly afterTokens?: number | null;
+    readonly missingSections?: readonly string[];
+}
+export interface CompactionQualityScore {
+    readonly qualityScore: number;
+    readonly compressionRatio: number | null;
+    readonly contractScore: number;
+    readonly compressionScore: number;
+    readonly evidenceScore: number;
+    readonly safetyScore: number;
+    readonly capabilityScore: number;
+}
+export declare const DEFAULT_STRUCTURED_COMPACTION_CONTRACT: StructuredCompactionContractV1;
+export declare const STRUCTURED_COMPACTION_V2_SCHEMA_VERSION: "omk.structured-compaction.v2";
+export interface CompactionQualityGateInput {
+    readonly applied: boolean;
+    readonly validated: boolean;
+    readonly qualityScore: number;
+    readonly contractScore: number;
+    readonly risk?: string;
+    readonly capabilities?: {
+        readonly write?: boolean;
+        readonly patch?: boolean;
+        readonly shell?: boolean;
+        readonly merge?: boolean;
+    };
+}
+export type CompactionGateDecision = "not-attempted" | "not-applied" | "accept" | "accept-with-warning" | "reject";
+export interface CompactionQualityGateResult {
+    readonly gateDecision: CompactionGateDecision;
+    readonly warning?: string;
+    readonly threshold: number;
+}
+export declare function resolveCompactionQualityThreshold(input: {
+    readonly risk?: string;
+    readonly capabilities?: CompactionQualityGateInput["capabilities"];
+}): number;
+export declare function evaluateCompactionQualityGate(input: CompactionQualityGateInput): CompactionQualityGateResult;
+export declare function validateStructuredCompaction(compactedText: string, capsule: ContextCapsule, contract?: StructuredCompactionContractV1): StructuredCompactionValidationResult;
+export declare function buildTypedStructuredCompactionContract(capsule: ContextCapsule): StructuredCompactionContractV2;
+export declare function renderTypedStructuredCompactionContract(contract: StructuredCompactionContractV2): string;
+export declare function parseTypedStructuredCompactionContract(compactedText: string): StructuredCompactionContractV2 | null;
+export declare function structuredCompactionGuardNote(result: StructuredCompactionValidationResult): string;
+export declare function structuredCompactionInstruction(contract?: StructuredCompactionContract): string;
+export declare function buildStructuredCompactionText(capsule: ContextCapsule, contract?: StructuredCompactionContractV1, options?: StructuredCompactionBuildOptions): string;
+export declare function estimateTextTokens(text: string, options?: TokenEstimationOptions): number;
+export declare function computeCompactionQualityScore(input: CompactionQualityInput): CompactionQualityScore;

package/dist/runtime/structured-compaction.js

@@ -0,0 +1,414 @@
+import { maskSensitiveText } from "../util/secret-mask.js";
+export const DEFAULT_STRUCTURED_COMPACTION_CONTRACT = {
+    schemaVersion: "omk.structured-compaction.v1",
+    requiredSections: [
+        "task",
+        "node routing",
+        "evidence requirements",
+        "safety constraints",
+        "capabilities",
+    ],
+    minTaskPrefixChars: 40,
+    safetyMarkers: ["preserve", "safety", "constraints", "evidence required", "capabilities"],
+};
+export const STRUCTURED_COMPACTION_V2_SCHEMA_VERSION = "omk.structured-compaction.v2";
+export function resolveCompactionQualityThreshold(input) {
+    const risk = (input.risk ?? "").toLowerCase();
+    const caps = input.capabilities ?? {};
+    if (caps.merge === true || caps.shell === true)
+        return 0.85;
+    if (caps.write === true || caps.patch === true)
+        return 0.75;
+    if (risk.includes("shell") || risk.includes("merge") || risk.includes("release"))
+        return 0.85;
+    if (risk.includes("write") || risk.includes("patch"))
+        return 0.75;
+    return 0.60;
+}
+function isStrictGuardrailMode() {
+    const raw = process.env.OMK_STRICT_GUARDRAIL ?? "";
+    const normalized = raw.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "on";
+}
+export function evaluateCompactionQualityGate(input) {
+    if (!input.applied) {
+        return { gateDecision: input.validated ? "not-applied" : "not-attempted", threshold: resolveCompactionQualityThreshold(input) };
+    }
+    const threshold = resolveCompactionQualityThreshold(input);
+    if (input.qualityScore >= threshold) {
+        return { gateDecision: "accept", threshold };
+    }
+    if (input.qualityScore >= Math.max(0, threshold - 0.20) && input.contractScore === 1) {
+        return { gateDecision: "accept-with-warning", warning: "low compaction quality", threshold };
+    }
+    if (!isStrictGuardrailMode()) {
+        return { gateDecision: "accept-with-warning", warning: "low compaction quality accepted under default freedom mode", threshold };
+    }
+    return {
+        gateDecision: "reject",
+        warning: "compaction quality below safety threshold",
+        threshold,
+    };
+}
+export function validateStructuredCompaction(compactedText, capsule, contract = DEFAULT_STRUCTURED_COMPACTION_CONTRACT) {
+    const typed = parseTypedStructuredCompactionContract(compactedText);
+    if (typed)
+        return validateTypedStructuredCompaction(compactedText, capsule, typed);
+    return validateLegacyStructuredCompaction(compactedText, capsule, contract);
+}
+function validateLegacyStructuredCompaction(compactedText, capsule, contract) {
+    const lower = compactedText.toLowerCase();
+    const missing = [];
+    if (contract.requiredSections.includes("task")) {
+        const taskLower = capsule.task.toLowerCase().trim();
+        const prefixLength = Math.min(contract.minTaskPrefixChars, taskLower.length);
+        if (taskLower.length > 0 && !lower.includes(taskLower.slice(0, prefixLength))) {
+            missing.push("task");
+        }
+    }
+    const routing = capsule.node.routing;
+    if (routing && contract.requiredSections.includes("node routing")) {
+        if (routing.provider && !lower.includes(routing.provider.toLowerCase()))
+            missing.push("node routing provider");
+        if (routing.risk && !lower.includes(routing.risk.toLowerCase()))
+            missing.push("node routing risk");
+        if (routing.sandboxMode && !lower.includes(routing.sandboxMode.toLowerCase()))
+            missing.push("node routing sandboxMode");
+        if (routing.readOnly === true && !lower.includes("read-only") && !lower.includes("readonly")) {
+            missing.push("node routing readOnly");
+        }
+    }
+    if (contract.requiredSections.includes("evidence requirements")) {
+        const requiredGates = capsule.evidenceRequirements
+            .filter((e) => e.required)
+            .map((e) => e.gate.toLowerCase());
+        if (requiredGates.length > 0 && !requiredGates.some((gate) => lower.includes(gate))) {
+            missing.push("evidence requirements");
+        }
+    }
+    if (contract.requiredSections.includes("safety constraints")) {
+        const systemLower = capsule.system.toLowerCase();
+        const hasSafetyMarker = contract.safetyMarkers.some((marker) => lower.includes(marker));
+        const hasSystemOverlap = systemLower.length > 0 && lower.includes(systemLower.slice(0, Math.min(60, systemLower.length)));
+        if (!hasSafetyMarker && !hasSystemOverlap)
+            missing.push("safety constraints");
+    }
+    if (contract.requiredSections.includes("capabilities")) {
+        const assignedCaps = new Set(routing?.assignedProviderCapabilities?.map((c) => c.toLowerCase()) ?? []);
+        if (assignedCaps.size > 0 && !Array.from(assignedCaps).some((cap) => lower.includes(cap))) {
+            missing.push("capabilities");
+        }
+    }
+    return { ok: missing.length === 0, missing, contract };
+}
+export function buildTypedStructuredCompactionContract(capsule) {
+    const routing = capsule.node.routing;
+    const requiredEvidence = capsule.evidenceRequirements
+        .filter((e) => e.required)
+        .map((e) => (e.ref ? { gate: e.gate, ref: e.ref } : { gate: e.gate }));
+    return {
+        schemaVersion: STRUCTURED_COMPACTION_V2_SCHEMA_VERSION,
+        node: {
+            id: capsule.nodeId,
+            role: String(capsule.node.role ?? "worker"),
+        },
+        routing: {
+            provider: routing?.provider ?? "auto",
+            risk: routing?.risk ?? "read",
+            sandboxMode: routing?.sandboxMode ?? "unknown",
+            readOnly: routing?.readOnly === true,
+            approvalPolicy: routing?.approvalPolicy ?? "unknown",
+        },
+        evidence: {
+            required: requiredEvidence,
+        },
+        capabilities: routing?.assignedProviderCapabilities ?? [],
+        safety: {
+            evidenceRequired: routing?.evidenceRequired === true || requiredEvidence.length > 0,
+            preserve: DEFAULT_STRUCTURED_COMPACTION_CONTRACT.requiredSections,
+        },
+    };
+}
+export function renderTypedStructuredCompactionContract(contract) {
+    return [
+        "```json omk.structured-compaction.v2",
+        JSON.stringify(contract, null, 2),
+        "```",
+    ].join("\n");
+}
+export function parseTypedStructuredCompactionContract(compactedText) {
+    const match = compactedText.match(/```json omk\.structured-compaction\.v2\s*\n([\s\S]*?)\n```/i);
+    if (!match)
+        return null;
+    try {
+        const parsed = JSON.parse(match[1]);
+        if (!isRecord(parsed) || parsed.schemaVersion !== STRUCTURED_COMPACTION_V2_SCHEMA_VERSION)
+            return null;
+        if (!isRecord(parsed.node) || typeof parsed.node.id !== "string" || typeof parsed.node.role !== "string")
+            return null;
+        if (!isRecord(parsed.routing))
+            return null;
+        if (!isRecord(parsed.evidence) || !Array.isArray(parsed.evidence.required))
+            return null;
+        if (!Array.isArray(parsed.capabilities))
+            return null;
+        if (!isRecord(parsed.safety) || !Array.isArray(parsed.safety.preserve))
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+function validateTypedStructuredCompaction(compactedText, capsule, contract) {
+    const missing = [];
+    const expected = buildTypedStructuredCompactionContract(capsule);
+    const lower = compactedText.toLowerCase();
+    for (const section of DEFAULT_STRUCTURED_COMPACTION_CONTRACT.requiredSections) {
+        if (!lower.includes(`## ${section}`))
+            missing.push(section);
+    }
+    if (contract.node.id !== expected.node.id)
+        missing.push("typed node id");
+    if (contract.node.role !== expected.node.role)
+        missing.push("typed node role");
+    if (contract.routing.provider !== expected.routing.provider)
+        missing.push("typed routing provider");
+    if (contract.routing.risk !== expected.routing.risk)
+        missing.push("typed routing risk");
+    if (contract.routing.sandboxMode !== expected.routing.sandboxMode)
+        missing.push("typed routing sandboxMode");
+    if (contract.routing.readOnly !== expected.routing.readOnly)
+        missing.push("typed routing readOnly");
+    if (contract.routing.approvalPolicy !== expected.routing.approvalPolicy)
+        missing.push("typed routing approvalPolicy");
+    if (!sameStringSet(contract.capabilities, expected.capabilities))
+        missing.push("typed capabilities");
+    if (!sameEvidence(contract.evidence.required, expected.evidence.required))
+        missing.push("typed evidence requirements");
+    if (contract.safety.evidenceRequired !== expected.safety.evidenceRequired)
+        missing.push("typed safety evidenceRequired");
+    if (!DEFAULT_STRUCTURED_COMPACTION_CONTRACT.requiredSections.every((section) => contract.safety.preserve.includes(section))) {
+        missing.push("typed safety preserve");
+    }
+    return { ok: missing.length === 0, missing, contract };
+}
+export function structuredCompactionGuardNote(result) {
+    return `Headroom compaction removed required sections: ${result.missing.join(", ")}; using original capsule.`;
+}
+export function structuredCompactionInstruction(contract = DEFAULT_STRUCTURED_COMPACTION_CONTRACT) {
+    if (contract.schemaVersion === STRUCTURED_COMPACTION_V2_SCHEMA_VERSION) {
+        return [
+            `${contract.schemaVersion}: the original context capsule was compacted before runtime dispatch.`,
+            "The typed JSON contract below is authoritative for routing, evidence, safety, and capabilities.",
+            "Preserve task, node routing, evidence requirements, safety constraints, and capability grants below.",
+        ].join(" ");
+    }
+    return [
+        `${contract.schemaVersion}: the original context capsule was compacted before runtime dispatch.`,
+        `Required sections: ${contract.requiredSections.join(", ")}.`,
+        "Preserve task, node routing, evidence requirements, safety constraints, and capability grants below.",
+    ].join(" ");
+}
+export function buildStructuredCompactionText(capsule, contract = DEFAULT_STRUCTURED_COMPACTION_CONTRACT, options = {}) {
+    const typedContract = buildTypedStructuredCompactionContract(capsule);
+    const routing = capsule.node.routing;
+    const redact = options.redact !== false;
+    const safe = (value, maxChars = 1_200) => truncateChars(redactText(String(value ?? ""), redact), maxChars);
+    const requiredEvidence = capsule.evidenceRequirements
+        .filter((e) => e.required)
+        .map((e) => `${safe(e.gate, 120)}${e.ref ? `:${safe(e.ref, 240)}` : ""}`)
+        .join(", ") || "none";
+    const capabilities = routing?.assignedProviderCapabilities?.map((cap) => safe(cap, 120)).join(", ") || "none";
+    const hardSections = [
+        structuredCompactionInstruction(typedContract),
+        renderTypedStructuredCompactionContract(typedContract),
+        "",
+        "## task",
+        safe(capsule.task, 1_600),
+        "",
+        "## node routing",
+        [
+            `node=${safe(capsule.nodeId, 160)}`,
+            `role=${safe(capsule.node.role, 120)}`,
+            `provider=${safe(routing?.provider ?? "auto", 120)}`,
+            `risk=${safe(routing?.risk ?? "read", 120)}`,
+            `sandboxMode=${safe(routing?.sandboxMode ?? "unknown", 120)}`,
+            `readOnly=${routing?.readOnly === true ? "read-only" : "write-capable"}`,
+            `approvalPolicy=${safe(routing?.approvalPolicy ?? "unknown", 120)}`,
+        ].join("; "),
+        "",
+        "## evidence requirements",
+        requiredEvidence,
+        "",
+        "## safety constraints",
+        [
+            "preserve safety constraints",
+            routing?.evidenceRequired ? "evidence required" : "evidence optional",
+            `goal=${safe(capsule.goal, 400)}`,
+            safe(capsule.system, 700),
+        ].filter(Boolean).join("; "),
+        "",
+        "## capabilities",
+        capabilities,
+    ].join("\n");
+    const targetTokens = Math.max(256, Math.floor(options.maxTokens ?? (capsule.budget.maxInputTokens - capsule.budget.reservedOutputTokens)));
+    const estimator = options.estimator;
+    let remainingTokens = Math.max(0, targetTokens - estimateTextTokens(hardSections, estimator));
+    const selected = selectCandidateSections(capsule, remainingTokens, options, redact);
+    return [hardSections, ...selected].join("\n");
+}
+function selectCandidateSections(capsule, budgetTokens, options, redact) {
+    const candidates = [];
+    const maxDeps = Math.max(0, options.maxDependencySummaries ?? 5);
+    for (const [index, summary] of capsule.dependencySummaries.slice(0, maxDeps).entries()) {
+        candidates.push({
+            heading: "dependency summaries",
+            text: redactText(summary, redact),
+            priority: 0.78 - index * 0.02,
+        });
+    }
+    const maxMemoryFacts = Math.max(0, options.maxMemoryFacts ?? capsule.budget.maxMemoryFacts);
+    for (const [index, fact] of capsule.graphMemory.slice(0, maxMemoryFacts).entries()) {
+        const text = redactText(`${fact.key}=${fact.value}`, redact);
+        candidates.push({
+            heading: "graph memory",
+            text,
+            priority: memoryPriority(fact.kind) - index * 0.01,
+        });
+    }
+    for (const [index, file] of capsule.relevantFiles.slice(0, 5).entries()) {
+        candidates.push({
+            heading: "file summaries",
+            text: redactText(`${file.path}:${file.startLine}-${file.endLine}\n${truncateChars(file.content, 1_000)}`, redact),
+            priority: 0.62 - index * 0.02,
+        });
+    }
+    for (const [index, attempt] of capsule.priorAttempts.slice(0, 5).entries()) {
+        candidates.push({
+            heading: "prior attempts",
+            text: redactText(`attempt=${attempt.attempt} provider=${attempt.provider} status=${attempt.status} durationMs=${attempt.durationMs ?? "?"} failure=${attempt.failureSummary ?? "none"}`, redact),
+            priority: 0.58 - index * 0.02,
+        });
+    }
+    const selected = {};
+    const sorted = candidates
+        .map((candidate) => ({ ...candidate, cost: Math.max(1, estimateTextTokens(candidate.text, options.estimator)) }))
+        .sort((a, b) => (b.priority / b.cost) - (a.priority / a.cost));
+    let remaining = budgetTokens;
+    for (const candidate of sorted) {
+        if (remaining <= 0)
+            break;
+        const cost = Math.max(1, estimateTextTokens(candidate.text, options.estimator));
+        const text = cost <= remaining
+            ? candidate.text
+            : truncateToTokenBudget(candidate.text, remaining);
+        if (!text.trim())
+            continue;
+        selected[candidate.heading] ??= [];
+        selected[candidate.heading].push(text);
+        remaining -= estimateTextTokens(text, options.estimator);
+    }
+    const headings = ["dependency summaries", "graph memory", "file summaries", "prior attempts"];
+    return headings.map((heading) => {
+        const lines = selected[heading];
+        return ["", `## ${heading}`, lines?.length ? lines.join(" | ") : "none"].join("\n");
+    });
+}
+function memoryPriority(kind) {
+    switch (kind) {
+        case "failure_pattern":
+        case "provider_behavior":
+            return 0.72;
+        case "architecture_decision":
+        case "api_contract":
+            return 0.66;
+        default:
+            return 0.54;
+    }
+}
+export function estimateTextTokens(text, options = {}) {
+    const base = Math.ceil(text.length / 4);
+    if (base <= 0)
+        return 0;
+    const hangulChars = text.match(/[\u3131-\u318E\uAC00-\uD7A3]/g)?.length ?? 0;
+    const hangulRatio = hangulChars / Math.max(1, text.length);
+    const hasJsonOrCode = /```|[{}[\]\s\S]*?:[\s\S]*?[}]|\b(function|class|interface|const|let|import|export)\b/.test(text);
+    const languageFactor = hangulRatio > 0.1 ? 1.25 : 1;
+    const structureFactor = hasJsonOrCode ? 1.10 : 1;
+    const multiplier = options.calibration?.multiplier ?? 1;
+    const bias = options.calibration?.bias ?? 0;
+    return Math.max(0, Math.ceil(base * languageFactor * structureFactor * multiplier + bias));
+}
+export function computeCompactionQualityScore(input) {
+    if (!input.applied) {
+        return {
+            qualityScore: 0,
+            compressionRatio: null,
+            contractScore: 0,
+            compressionScore: 0,
+            evidenceScore: 0,
+            safetyScore: 0,
+            capabilityScore: 0,
+        };
+    }
+    const before = Math.max(1, input.beforeTokens ?? 0);
+    const after = Math.max(0, input.afterTokens ?? 0);
+    const compressionRatio = after / before;
+    const compressionScore = clamp01(1 - compressionRatio);
+    const missing = new Set(input.missingSections ?? []);
+    const contractScore = input.validated ? 1 : 0;
+    const evidenceScore = missing.has("evidence requirements") || missing.has("typed evidence requirements") ? 0 : 1;
+    const safetyScore = missing.has("safety constraints") || missing.has("typed safety evidenceRequired") || missing.has("typed safety preserve") ? 0 : 1;
+    const capabilityScore = missing.has("capabilities") || missing.has("typed capabilities") ? 0 : 1;
+    const qualityScore = clamp01(0.35 * contractScore
+        + 0.25 * compressionScore
+        + 0.15 * evidenceScore
+        + 0.15 * safetyScore
+        + 0.10 * capabilityScore);
+    return {
+        qualityScore,
+        compressionRatio,
+        contractScore,
+        compressionScore,
+        evidenceScore,
+        safetyScore,
+        capabilityScore,
+    };
+}
+function clamp01(value) {
+    return Math.max(0, Math.min(1, value));
+}
+function truncateToTokenBudget(text, budgetTokens) {
+    const maxChars = Math.max(0, budgetTokens * 4);
+    return truncateChars(text, maxChars);
+}
+function truncateChars(text, maxChars) {
+    if (maxChars <= 0)
+        return "";
+    if (text.length <= maxChars)
+        return text;
+    if (maxChars <= 16)
+        return text.slice(0, maxChars);
+    return `${text.slice(0, maxChars - 16)}…[truncated]`;
+}
+function redactText(text, redact) {
+    return redact ? maskSensitiveText(text) : text;
+}
+function sameStringSet(a, b) {
+    const left = new Set(a);
+    const right = new Set(b);
+    if (left.size !== right.size)
+        return false;
+    for (const value of left)
+        if (!right.has(value))
+            return false;
+    return true;
+}
+function sameEvidence(a, b) {
+    const key = (item) => `${item.gate}\u0000${item.ref ?? ""}`;
+    return sameStringSet(a.map(key), b.map(key));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}

package/dist/runtime/tool-dispatch-contracts.d.ts

@@ -8,8 +8,8 @@ export interface ToolDispatchResult<R = unknown> {
     readonly value?: R;
     readonly reason?: unknown;
 }
-/** Shadow = record only; enforce = a block/ask(non-TTY) verdict rejects the call. */
-export type ToolAuthorityMode = "shadow" | "enforce";
+/** Shadow = record only; warn = visible diagnostic; enforce = a block/ask(non-TTY) verdict rejects the call. */
+export type ToolAuthorityMode = "shadow" | "warn" | "enforce";
 /**
  * Per-call verdict recorded at the dispatch checkpoint. Carries only coarse,
  * non-secret signals (op class, authority levels, policy) — never tool args.
@@ -68,10 +68,12 @@ export interface ToolAuthorityWiring {
     readonly resolveWritePath?: (call: OmkToolCall) => string | undefined;
 }
 /**
- * Resolve the global enforcement opt-in from the environment. Default OFF means
- * the gate runs in shadow mode (record only). Set `OMK_TOOL_AUTHORITY_ENFORCE=1`
- * to enable fail-closed enforcement at the dispatch checkpoint.
+ * Resolve staged authority mode from the environment. Default OFF means the gate
+ * runs in shadow mode (record only). `warn` emits visible diagnostics without
+ * blocking. `enforce` fail-closes block/ask(non-TTY) verdicts.
  */
+export declare function resolveToolAuthorityMode(env?: Record<string, string | undefined>): ToolAuthorityMode;
+/** Backward-compatible boolean resolver for existing dispatch call sites. */
 export declare function resolveToolAuthorityEnforcement(env?: Record<string, string | undefined>): boolean;
 /** Error used to reject a tool call rejected by the authority gate (enforce mode). */
 export declare class ToolAuthorityBlockedError extends Error {

package/dist/runtime/tool-dispatch-contracts.js

@@ -3,12 +3,23 @@ import { decideToolAuthority, decideToolAuthorityV2, mapToolNameToOp, } from "..
 import { assertWritable } from "./sandbox-profile.js";
 const ENFORCE_PATTERN = /^(1|true|yes|on)$/i;
 /**
- * Resolve the global enforcement opt-in from the environment. Default OFF means
- * the gate runs in shadow mode (record only). Set `OMK_TOOL_AUTHORITY_ENFORCE=1`
- * to enable fail-closed enforcement at the dispatch checkpoint.
+ * Resolve staged authority mode from the environment. Default OFF means the gate
+ * runs in shadow mode (record only). `warn` emits visible diagnostics without
+ * blocking. `enforce` fail-closes block/ask(non-TTY) verdicts.
  */
+export function resolveToolAuthorityMode(env = process.env) {
+    const rawMode = (env.OMK_TOOL_AUTHORITY_MODE ?? "").trim().toLowerCase();
+    if (rawMode === "enforce" || rawMode === "warn" || rawMode === "shadow")
+        return rawMode;
+    if (ENFORCE_PATTERN.test((env.OMK_TOOL_AUTHORITY_ENFORCE ?? "").trim()))
+        return "enforce";
+    if (ENFORCE_PATTERN.test((env.OMK_TOOL_AUTHORITY_WARN ?? "").trim()))
+        return "warn";
+    return "shadow";
+}
+/** Backward-compatible boolean resolver for existing dispatch call sites. */
 export function resolveToolAuthorityEnforcement(env = process.env) {
-    return ENFORCE_PATTERN.test((env.OMK_TOOL_AUTHORITY_ENFORCE ?? "").trim());
+    return resolveToolAuthorityMode(env) === "enforce";
 }
 /** Build a redacted reason string from non-secret authority signals only. */
 function redactedAuthorityReason(op, decision, wiring) {

package/dist/runtime/tool-plane.d.ts

@@ -2,7 +2,7 @@ import type { OmkRuntimeScope } from "../util/resource-profile.js";
 import { type OmkToolPrefixSpec } from "./tool-registry-contract.js";
 export interface OmkToolPlaneDiagnostic {
     readonly level: "warning" | "error";
-    readonly code: "mcp_config_parse_failed" | "mcp_config_read_failed" | "runtime_mcp_config_parse_failed" | "runtime_mcp_required_unavailable";
+    readonly code: "mcp_config_parse_failed" | "mcp_config_read_failed" | "runtime_mcp_config_parse_failed" | "runtime_mcp_required_unavailable" | "skill_reference_unknown" | "skill_config_read_failed" | "hook_reference_unknown" | "hook_config_read_failed";
     readonly path?: string;
     readonly message: string;
 }

package/dist/runtime/tool-plane.js

@@ -7,7 +7,9 @@ export async function buildOmkToolPlaneManifest(input) {
     const requiresRuntimeMcp = input.requiresRuntimeMcp === true;
     const resolved = await resolveRuntimeMcpConfigFile(input.mcpScope, input.mcpAllowlist);
     const runtimeRead = resolved.mcpConfigFile ? await readMcpServerNames(resolved.mcpConfigFile) : { servers: [], diagnostics: [] };
-    const diagnostics = [...resolved.diagnostics, ...runtimeRead.diagnostics];
+    const skillDiagnostics = await validateSkillReferences(input.skills ?? []);
+    const hookDiagnostics = await validateHookReferences(input.hooks ?? []);
+    const diagnostics = [...resolved.diagnostics, ...runtimeRead.diagnostics, ...skillDiagnostics, ...hookDiagnostics];
     if (requiresRuntimeMcp && (diagnostics.some((diagnostic) => diagnostic.level === "error") || !resolved.mcpConfigFile || runtimeRead.servers.length === 0)) {
         throw new Error(formatRequiredRuntimeMcpError(diagnostics, resolved.mcpConfigFile, runtimeRead.servers));
     }
@@ -97,6 +99,52 @@ function mcpDiagnosticMessage(err) {
     }
     return "invalid MCP config";
 }
+async function validateSkillReferences(skills) {
+    if (skills.length === 0)
+        return [];
+    const diagnostics = [];
+    const projectRoot = resolve(await getProjectRootAsync());
+    for (const skill of skills) {
+        const safeName = skill.replace(/[^a-zA-Z0-9_-]/g, "");
+        if (safeName !== skill) {
+            diagnostics.push({ level: "warning", code: "skill_reference_unknown", message: `skill name contains unsafe characters: ${skill}` });
+            continue;
+        }
+        const paths = [
+            resolve(projectRoot, ".agents/skills", safeName, "SKILL.md"),
+            resolve(projectRoot, ".kimi/skills", safeName, "SKILL.md"),
+            resolve(getUserHome(), ".omk/agent/skills", safeName, "SKILL.md"),
+        ];
+        const found = await Promise.all(paths.map((p) => readFile(p, "utf-8").then(() => true).catch(() => false)));
+        if (!found.some(Boolean)) {
+            diagnostics.push({ level: "warning", code: "skill_reference_unknown", message: `skill not found in project or user skill paths: ${skill}` });
+        }
+    }
+    return diagnostics;
+}
+async function validateHookReferences(hooks) {
+    if (hooks.length === 0)
+        return [];
+    const diagnostics = [];
+    const projectRoot = resolve(await getProjectRootAsync());
+    for (const hook of hooks) {
+        const safeName = hook.replace(/[^a-zA-Z0-9_.-]/g, "");
+        if (safeName !== hook) {
+            diagnostics.push({ level: "warning", code: "hook_reference_unknown", message: `hook name contains unsafe characters: ${hook}` });
+            continue;
+        }
+        const paths = [
+            resolve(projectRoot, ".agents/hooks", safeName),
+            resolve(projectRoot, ".kimi/hooks", safeName),
+            resolve(getUserHome(), ".omk/agent/hooks", safeName),
+        ];
+        const found = await Promise.all(paths.map((p) => readFile(p, "utf-8").then(() => true).catch(() => false)));
+        if (!found.some(Boolean)) {
+            diagnostics.push({ level: "warning", code: "hook_reference_unknown", message: `hook not found in project or user hook paths: ${hook}` });
+        }
+    }
+    return diagnostics;
+}
 function formatRequiredRuntimeMcpError(diagnostics, mcpConfigFile, servers) {
     const errors = diagnostics
         .filter((diagnostic) => diagnostic.level === "error")

package/dist/runtime/worker-manifest.js

@@ -138,7 +138,7 @@ function deriveWorkerCapabilities(node, toolPlane) {
     const role = node.role?.toLowerCase() ?? "";
     const gates = node.outputs?.map((output) => output.gate).filter(Boolean) ?? [];
     const assigned = new Set(routing?.assignedProviderCapabilities ?? []);
-    const readOnly = routing?.readOnly === true;
+    const readOnly = routing?.readOnly === true || routing?.freedomd?.degradedMode === "read-only-local-review";
     const merge = !readOnly && (assigned.has("merge") || role === "merger" || role === "integrator" || role === "orchestrator");
     const write = !readOnly && (assigned.has("write") || merge || role === "coder" || role === "executor" || role === "refactorer");
     const shell = !readOnly && (assigned.has("shell") || routing?.requiresToolCalling === true || gates.includes("command-pass") || gates.includes("test-pass"));