@hassangameryt/freeflow 0.5.0 → 0.7.0

package/pi-extension/dist/runtime/runtime-context.js

@@ -1,17 +1,16 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { normalizeFreeflowConfig, normalizeLocalFreeflowConfig } from "../../../router/dist/index.js";
-export const VALID_MODES = new Set(["conversation", "workflow", "strict-workflow"]);
+import { resolveCognitiveRoutingState } from "../cognitive-routing/runtime.js";
+import { supportsCognitiveRoutingModelRegistry } from "../cognitive-routing/host.js";
 export const WORKFLOW_COMMANDS = [
   { command: "discuss", skill: "discuss" },
-  { command: "discover", skill: "discuss" },
+  { command: "action-selection", skill: "action-selection" },
   { command: "track-work", skill: "track-work" },
   { command: "write-spec", skill: "write-spec" },
   { command: "review-artifact", skill: "review-artifact" },
   { command: "write-plan", skill: "write-plan" },
   { command: "execute-work", skill: "execute-work" },
-  { command: "execute-plan", skill: "execute-work" },
   { command: "simplify-code", skill: "simplify-code" },
   { command: "migration-work", skill: "migration-work" },
   { command: "diagnose-failure", skill: "diagnose-failure" },
@@ -26,6 +25,7 @@ export const WORKFLOW_COMMANDS = [
 ];
 export const CONTRIBUTOR_COMMANDS = ["setup-freeflow", "write-skill", "evaluate-skill"];
 export const FREEFLOW_MODEL_SKILL_NAMES = [
+  "action-selection",
   "bypass",
   "commit-work",
   "decision-gate",
@@ -37,7 +37,6 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "execute-work",
   "finish-branch",
   "handoff",
-  "mode-contract",
   "release-work",
   "review-artifact",
   "review-work",
@@ -52,54 +51,99 @@ export const FREEFLOW_MODEL_SKILL_NAMES = [
   "write-skill",
   "write-spec",
 ];
+export const FREEFLOW_CAPABILITY_SKILL_NAMES = ["cognitive-routing", "context-virtualization", "conversation-history"];
 export function freeflowSkillPath(skillName) {
   return fileURLToPath(new URL(`../../../skills/${skillName}/SKILL.md`, import.meta.url));
 }
-export function freeflowModelSkillPaths() {
-  return FREEFLOW_MODEL_SKILL_NAMES.map((skillName) => freeflowSkillPath(skillName));
+export function freeflowCapabilitySkillPath(skillName) {
+  return fileURLToPath(new URL(`../../../capabilities/${skillName}/SKILL.md`, import.meta.url));
+}
+export function freeflowModelSkillPaths(capabilityState = undefined) {
+  const paths = FREEFLOW_MODEL_SKILL_NAMES.map((skillName) => freeflowSkillPath(skillName));
+  const capabilityStates = {
+    "cognitive-routing": capabilityState?.cognitiveRouting,
+    "context-virtualization": capabilityState?.contextVirtualization,
+    "conversation-history": capabilityState?.conversationHistory,
+  };
+  for (const skillName of FREEFLOW_CAPABILITY_SKILL_NAMES) {
+    if (capabilityStates[skillName]?.effective === true) {
+      paths.push(freeflowCapabilitySkillPath(skillName));
+    }
+  }
+  return paths;
 }
-const MODE_STATE_ENTRY = "freeflow-mode";
 const SESSION_OVERRIDES_ENTRY = "freeflow-session-overrides";
-const SESSION_CORE_KEYS = new Set(["enabled", "interactionContract", "skillsEnabled"]);
-const RESET_MODE_ARGS = new Set(["reset"]);
-export const FREEFLOW_STATUS_TOOL_NAME = "freeflow_status";
-export const OUTPUT_ROUTER_TOOL_NAMES = ["freeflow_search", "freeflow_run", "freeflow_batch"];
+const SESSION_CORE_KEYS = new Set(["enabled", "contextVirtualization", "conversationHistory"]);
+export const COGNITIVE_ROUTING_SWITCH_TOOL_NAME = "freeflow_switch_profile";
+export const FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-runtime-state";
+export const COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE = "freeflow-cognitive-routing-runtime-state";
 export const WORKFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-workflow-bootstrap";
+export const COGNITIVE_ROUTING_BOOTSTRAP_MESSAGE_TYPE = "freeflow-cognitive-routing-bootstrap";
+export const FREEFLOW_BOOTSTRAP_MESSAGE_TYPE = "freeflow-bootstrap";
 let runtimeContextCache = null;
-let currentModeOverride = null;
 let currentSessionOverrides = {};
-let lastRouterConfigWarningKey = null;
+export function isPromptAvailable(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+export function hasUsableMandatoryPrompts(freeflowContext) {
+  return (
+    isPromptAvailable(freeflowContext?.corePrompt) && isPromptAvailable(freeflowContext?.interactionContractPrompt)
+  );
+}
+async function readPromptFile(url) {
+  try {
+    const prompt = await readFile(url, "utf8");
+    return isPromptAvailable(prompt) ? prompt.trim() : null;
+  } catch {
+    return null;
+  }
+}
 async function loadRuntimeContext(capabilityState = undefined) {
-  const interactionContractEnabled = capabilityState?.interactionContract?.effective === true;
-  const skillsEnabled = capabilityState?.skills?.effective === true;
-  const outputRouterEnabled = capabilityState?.outputRouter?.enabled === true;
-  const [interactionContract, workflowSkill, outputRouterSkill] = await Promise.all([
-    interactionContractEnabled
-      ? readFile(new URL("../../../runtime/interaction-contract.md", import.meta.url), "utf8")
+  const freeflowEnabled = capabilityState?.enabled === true;
+  const contextVirtualizationEnabled = capabilityState?.contextVirtualization?.effective === true;
+  const conversationHistoryEnabled = capabilityState?.conversationHistory?.effective === true;
+  const cognitiveRoutingEnabled = capabilityState?.cognitiveRouting?.effective === true;
+  const [
+    corePrompt,
+    interactionContractPrompt,
+    cognitiveRoutingPrompt,
+    contextVirtualizationPrompt,
+    conversationHistoryPrompt,
+  ] = await Promise.all([
+    freeflowEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/core.md", import.meta.url))
+      : Promise.resolve(null),
+    freeflowEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/interaction-contract.md", import.meta.url))
+      : Promise.resolve(null),
+    cognitiveRoutingEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/cognitive-routing.md", import.meta.url))
       : Promise.resolve(null),
-    skillsEnabled
-      ? readFile(new URL("../../../skills/workflow/SKILL.md", import.meta.url), "utf8")
+    contextVirtualizationEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/context-virtualization.md", import.meta.url))
       : Promise.resolve(null),
-    outputRouterEnabled
-      ? readFile(new URL("../../../capabilities/output-router/SKILL.md", import.meta.url), "utf8")
+    conversationHistoryEnabled
+      ? readPromptFile(new URL("../../../runtime/prompts/conversation-history.md", import.meta.url))
       : Promise.resolve(null),
   ]);
-  return { interactionContract, workflowSkill, outputRouterSkill };
+  return {
+    corePrompt,
+    interactionContractPrompt,
+    cognitiveRoutingPrompt,
+    contextVirtualizationPrompt,
+    conversationHistoryPrompt,
+  };
 }
 function runtimeContextCacheSatisfies(capabilityState) {
-  if (!runtimeContextCache) {
-    return false;
-  }
-  if (capabilityState?.interactionContract?.effective === true && !runtimeContextCache.interactionContract) {
-    return false;
-  }
-  if (capabilityState?.skills?.effective === true && !runtimeContextCache.workflowSkill) {
-    return false;
-  }
-  if (capabilityState?.outputRouter?.enabled === true && !runtimeContextCache.outputRouterSkill) {
-    return false;
-  }
-  return true;
+  if (!runtimeContextCache) return false;
+  const expected = {
+    corePrompt: capabilityState?.enabled === true,
+    interactionContractPrompt: capabilityState?.enabled === true,
+    cognitiveRoutingPrompt: capabilityState?.cognitiveRouting?.effective === true,
+    contextVirtualizationPrompt: capabilityState?.contextVirtualization?.effective === true,
+    conversationHistoryPrompt: capabilityState?.conversationHistory?.effective === true,
+  };
+  return Object.entries(expected).every(([key, required]) => !required || isPromptAvailable(runtimeContextCache[key]));
 }
 export async function refreshRuntimeContext(capabilityState = undefined) {
   runtimeContextCache = await loadRuntimeContext(capabilityState);
@@ -111,67 +155,45 @@ export async function getRuntimeContext(capabilityState = undefined) {
   }
   return refreshRuntimeContext(capabilityState);
 }
-function activeSessionEntries(sessionManager) {
-  try {
-    if (typeof sessionManager?.buildContextEntries === "function") {
-      const entries = sessionManager.buildContextEntries();
-      if (Array.isArray(entries)) {
-        return entries;
-      }
-    }
-    if (typeof sessionManager?.getEntries === "function") {
-      const entries = sessionManager.getEntries();
-      if (Array.isArray(entries)) {
-        return entries;
-      }
-    }
-  } catch {
-    // A missing session snapshot should reload useful context rather than suppress it.
+const BOOTSTRAP_COMPONENTS = Object.freeze({
+  workflow: "workflow",
+  cognitiveRouting: "cognitive-routing",
+});
+function bootstrapEntryComponents(entry) {
+  const isCustomMessage = entry?.role === "custom" || entry?.type === "custom_message" || entry?.type === "custom";
+  if (!isCustomMessage) return [];
+  if (entry.customType === FREEFLOW_BOOTSTRAP_MESSAGE_TYPE) {
+    if (Array.isArray(entry.details?.components)) return entry.details.components;
+    return [
+      ...(entry.content?.includes("<!-- freeflow-bootstrap:workflow -->") ? [BOOTSTRAP_COMPONENTS.workflow] : []),
+      ...(entry.content?.includes("<!-- freeflow-bootstrap:cognitive-routing -->")
+        ? [BOOTSTRAP_COMPONENTS.cognitiveRouting]
+        : []),
+    ];
+  }
+  if (entry.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE) {
+    return [BOOTSTRAP_COMPONENTS.workflow];
+  }
+  if (entry.customType === COGNITIVE_ROUTING_BOOTSTRAP_MESSAGE_TYPE) {
+    return [BOOTSTRAP_COMPONENTS.cognitiveRouting];
   }
   return [];
 }
-export function workflowBootstrapMessage(freeflowContext, capabilityState, sessionManager) {
-  if (capabilityState?.skills?.effective !== true || !freeflowContext?.workflowSkill) {
-    return undefined;
-  }
-  const alreadyLoaded = activeSessionEntries(sessionManager).some(
-    (entry) => entry?.type === "custom_message" && entry?.customType === WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
-  );
-  if (alreadyLoaded) {
-    return undefined;
-  }
-  return {
-    customType: WORKFLOW_BOOTSTRAP_MESSAGE_TYPE,
-    content: `# Freeflow Workflow Bootstrap\n\n${freeflowContext.workflowSkill.trim()}`,
-    display: false,
-    details: { skill: "workflow", source: "first-turn-bootstrap" },
-  };
+export function filterBootstrapMessage(message) {
+  return bootstrapEntryComponents(message).length === 0 ? message : undefined;
 }
 function isRecord(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function validateCoreConfigFields(value) {
-  if (value.defaultMode !== undefined && !VALID_MODES.has(value.defaultMode)) {
-    return `invalid defaultMode: ${JSON.stringify(value.defaultMode)}`;
-  }
   if (value.enabled !== undefined && typeof value.enabled !== "boolean") {
     return "enabled must be a boolean";
   }
-  if (value.interactionContract !== undefined && typeof value.interactionContract !== "boolean") {
-    return "interactionContract must be a boolean";
+  if (value.contextVirtualization !== undefined && typeof value.contextVirtualization !== "boolean") {
+    return "contextVirtualization must be a boolean";
   }
-  if (value.skills !== undefined) {
-    if (!isRecord(value.skills)) {
-      return "skills must be an object";
-    }
-    for (const key of Object.keys(value.skills)) {
-      if (key !== "enabled") {
-        return `unsupported skills config key: ${key}`;
-      }
-    }
-    if (value.skills.enabled !== undefined && typeof value.skills.enabled !== "boolean") {
-      return "skills.enabled must be a boolean";
-    }
+  if (value.conversationHistory !== undefined && typeof value.conversationHistory !== "boolean") {
+    return "conversationHistory must be a boolean";
   }
   return null;
 }
@@ -179,14 +201,15 @@ function validateFreeflowConfigShape(value) {
   if (!isRecord(value)) {
     return "config must be a JSON object";
   }
+  // Keep retired capability keys shape-tolerated so existing repositories remain activated; runtime behavior ignores them.
   const allowedKeys = new Set([
     "enabled",
-    "defaultMode",
-    "interactionContract",
-    "skills",
     "outputRouter",
     "observedRouting",
     "scriptTransform",
+    "cognitiveRouting",
+    "contextVirtualization",
+    "conversationHistory",
   ]);
   for (const key of Object.keys(value)) {
     if (!allowedKeys.has(key)) {
@@ -206,7 +229,13 @@ function validateFreeflowLocalConfigShape(value) {
   if (!isRecord(value)) {
     return "local config must be a JSON object";
   }
-  const allowedKeys = new Set(["enabled", "defaultMode", "interactionContract", "skills", "processing"]);
+  const allowedKeys = new Set([
+    "enabled",
+    "processing",
+    "cognitiveRouting",
+    "contextVirtualization",
+    "conversationHistory",
+  ]);
   for (const key of Object.keys(value)) {
     if (!allowedKeys.has(key)) {
       return `unsupported top-level local config key: ${key}`;
@@ -275,23 +304,18 @@ function resolveLayeredValue(repository, local, key, fallback) {
 }
 function resolveCoreConfig(repository, local) {
   const enabled = resolveLayeredValue(repository, local, "enabled", true);
-  const interactionContract = resolveLayeredValue(repository, local, "interactionContract", true);
-  const defaultMode = resolveLayeredValue(repository, local, "defaultMode", "workflow");
-  const repositorySkills = isRecord(repository.skills) ? repository.skills : {};
-  const localSkills = isRecord(local.skills) ? local.skills : {};
-  const skillsEnabled = resolveLayeredValue(repositorySkills, localSkills, "enabled", true);
+  const contextVirtualization = resolveLayeredValue(repository, local, "contextVirtualization", false);
+  const conversationHistory = resolveLayeredValue(repository, local, "conversationHistory", false);
   return {
     config: {
       enabled: enabled.value,
-      interactionContract: interactionContract.value,
-      skills: { enabled: skillsEnabled.value },
-      defaultMode: defaultMode.value,
+      contextVirtualization: contextVirtualization.value,
+      conversationHistory: conversationHistory.value,
     },
     sources: {
       enabled: enabled.source,
-      interactionContract: interactionContract.source,
-      skillsEnabled: skillsEnabled.source,
-      defaultMode: defaultMode.source,
+      contextVirtualization: contextVirtualization.source,
+      conversationHistory: conversationHistory.source,
     },
   };
 }
@@ -309,21 +333,20 @@ function resolveSessionCoreConfig(layers) {
   const configured = layers.coreConfig;
   const sources = layers.sources;
   const enabled = currentSessionOverrides.enabled;
-  const interactionContract = currentSessionOverrides.interactionContract;
-  const skillsEnabled = currentSessionOverrides.skillsEnabled;
+  const contextVirtualization = currentSessionOverrides.contextVirtualization;
+  const conversationHistory = currentSessionOverrides.conversationHistory;
   return {
     config: {
       enabled: typeof enabled === "boolean" ? enabled : configured.enabled,
-      interactionContract:
-        typeof interactionContract === "boolean" ? interactionContract : configured.interactionContract,
-      skills: { enabled: typeof skillsEnabled === "boolean" ? skillsEnabled : configured.skills.enabled },
-      defaultMode: configured.defaultMode,
+      contextVirtualization:
+        typeof contextVirtualization === "boolean" ? contextVirtualization : configured.contextVirtualization,
+      conversationHistory:
+        typeof conversationHistory === "boolean" ? conversationHistory : configured.conversationHistory,
     },
     sources: {
       enabled: typeof enabled === "boolean" ? "session" : sources.enabled,
-      interactionContract: typeof interactionContract === "boolean" ? "session" : sources.interactionContract,
-      skillsEnabled: typeof skillsEnabled === "boolean" ? "session" : sources.skillsEnabled,
-      defaultMode: sources.defaultMode,
+      contextVirtualization: typeof contextVirtualization === "boolean" ? "session" : sources.contextVirtualization,
+      conversationHistory: typeof conversationHistory === "boolean" ? "session" : sources.conversationHistory,
     },
   };
 }
@@ -351,15 +374,32 @@ export async function readFreeflowConfigLayers(cwd) {
     parseError: blockingState?.parseError ?? null,
   };
 }
-export async function readCapabilityState(cwd) {
+export async function readCapabilityState(cwd, host = undefined, extensionHost = undefined) {
   const layers = await readFreeflowConfigLayers(cwd);
-  const parsed = layers.repository.valid ? layers.repository.parsed : {};
-  const normalized = normalizeFreeflowConfig(parsed);
   const effectiveCore = resolveSessionCoreConfig(layers);
   const enabled = layers.configured && effectiveCore.config.enabled;
-  const interactionContractConfigEnabled = effectiveCore.config.interactionContract;
-  const skillsConfigEnabled = effectiveCore.config.skills.enabled;
-  const outputRouterConfigEnabled = normalized.config.outputRouter.enabled;
+  const contextVirtualizationConfigEnabled = effectiveCore.config.contextVirtualization;
+  const conversationHistoryConfigEnabled = effectiveCore.config.conversationHistory;
+  const hostSupportsCognitiveRouting = supportsCognitiveRoutingModelRegistry(host);
+  const configuredCognitiveRouting = await resolveCognitiveRoutingState(
+    layers.repository.parsed,
+    layers.local.parsed,
+    hostSupportsCognitiveRouting ? host : undefined,
+  );
+  const disabledReason = enabled ? undefined : { code: "disabled", message: "Freeflow is disabled" };
+  const childCapability = (configuredEnabled) => ({
+    enabled: configuredEnabled,
+    effective: enabled && configuredEnabled,
+    ...(disabledReason ? { blockingReason: disabledReason } : {}),
+  });
+  const cognitiveRouting = enabled
+    ? configuredCognitiveRouting
+    : {
+        ...configuredCognitiveRouting,
+        enabled: false,
+        effective: false,
+        blockingReason: disabledReason,
+      };
   return {
     configured: layers.configured,
     repositoryConfigured: layers.repositoryConfigured,
@@ -375,111 +415,30 @@ export async function readCapabilityState(cwd) {
     configuredSources: layers.sources,
     sessionOverrides: { ...currentSessionOverrides },
     configSources: effectiveCore.sources,
-    defaultMode: effectiveCore.config.defaultMode,
     enabled,
-    interactionContract: {
-      enabled: interactionContractConfigEnabled,
-      effective: enabled && interactionContractConfigEnabled,
-    },
-    skills: {
-      enabled: skillsConfigEnabled,
-      effective: enabled && skillsConfigEnabled,
-    },
-    outputRouter: {
-      enabled: enabled && outputRouterConfigEnabled,
-      configEnabled: outputRouterConfigEnabled,
-    },
+    contextVirtualization: childCapability(contextVirtualizationConfigEnabled),
+    conversationHistory: childCapability(conversationHistoryConfigEnabled),
+    hostSupportsCognitiveRouting,
+    cognitiveRouting,
   };
 }
 export const readRuntimeState = readCapabilityState;
-export async function readOutputRouterConfig(cwd) {
-  const layers = await readFreeflowConfigLayers(cwd);
-  const parsed = layers.repository.valid ? layers.repository.parsed : {};
-  const localParsed = layers.local.valid ? layers.local.parsed : {};
-  const normalized = normalizeFreeflowConfig(parsed);
-  const local = normalizeLocalFreeflowConfig(localParsed);
-  const freeflowEnabled = layers.configured && layers.coreConfig.enabled;
-  const effectiveConfig = freeflowEnabled
-    ? normalized.config
-    : {
-        ...normalized.config,
-        outputRouter: { ...normalized.config.outputRouter, enabled: false },
-        observedRouting: {
-          ...normalized.config.observedRouting,
-          enabled: false,
-        },
-        scriptTransform: {
-          ...normalized.config.scriptTransform,
-          enabled: false,
-        },
-      };
-  const configWarnings = [...normalized.warnings];
-  if (layers.repository.exists && !layers.repository.valid) {
-    configWarnings.unshift(
-      `.freeflow/config.json could not be parsed; Freeflow runtime is inactive. ${layers.repository.parseError ?? ""}`.trim(),
-    );
-  }
-  if (layers.local.exists && !layers.local.valid) {
-    configWarnings.unshift(
-      `.freeflow/local.json could not be parsed; Freeflow runtime is inactive. ${layers.local.parseError ?? ""}`.trim(),
-    );
-  }
-  return {
-    config: effectiveConfig.outputRouter,
-    freeflowConfig: effectiveConfig,
-    localConfig: local.config,
-    warnings: [...configWarnings, ...local.warnings],
-  };
-}
-export function notifyRouterConfigWarnings(ctx, routerConfigResult) {
-  if (!routerConfigResult.warnings.length) {
-    return;
-  }
-  const key = routerConfigResult.warnings.join("\n");
-  if (key === lastRouterConfigWarningKey) {
-    return;
-  }
-  lastRouterConfigWarningKey = key;
-  ctx.ui.notify(`Freeflow config warning: ${routerConfigResult.warnings.join(" ")}`, "warning");
-}
-export function restoreModeOverride(ctx) {
-  currentModeOverride = null;
+export function restoreSessionOverrides(ctx) {
   currentSessionOverrides = {};
   const entries = ctx.sessionManager?.getBranch?.() ?? ctx.sessionManager?.getEntries?.() ?? [];
   for (const entry of entries) {
-    if (entry.type !== "custom") continue;
-    if (entry.customType === MODE_STATE_ENTRY) {
-      const mode = entry.data?.currentMode;
-      currentModeOverride = VALID_MODES.has(mode) ? mode : null;
-    } else if (entry.customType === SESSION_OVERRIDES_ENTRY) {
+    if (entry.type === "custom" && entry.customType === SESSION_OVERRIDES_ENTRY) {
       currentSessionOverrides = normalizeSessionOverrides(entry.data?.overrides);
     }
   }
 }
-export async function readModeState(cwd) {
-  const layers = await readFreeflowConfigLayers(cwd);
-  const effectiveCore = resolveSessionCoreConfig(layers);
-  const repositoryDefaultMode = VALID_MODES.has(layers.repository.parsed.defaultMode)
-    ? layers.repository.parsed.defaultMode
-    : "workflow";
-  const personalDefaultMode = VALID_MODES.has(layers.local.parsed.defaultMode) ? layers.local.parsed.defaultMode : null;
-  const sessionMode = VALID_MODES.has(currentModeOverride) ? currentModeOverride : null;
-  const resolvedMode = sessionMode ?? effectiveCore.config.defaultMode;
-  const active = layers.configured && effectiveCore.config.enabled && effectiveCore.config.skills.enabled;
-  return {
-    repositoryDefaultMode,
-    repositoryDefaultModeSource: VALID_MODES.has(layers.repository.parsed.defaultMode) ? "repository" : "builtin",
-    personalDefaultMode,
-    defaultMode: effectiveCore.config.defaultMode,
-    defaultModeSource: effectiveCore.sources.defaultMode,
-    currentMode: sessionMode,
-    sessionMode,
-    resolvedMode,
-    active,
-    effectiveMode: active ? resolvedMode : null,
-  };
-}
-export function setModeStatus(ctx, modeState, capabilityState = undefined) {
+export function setFreeflowStatus(
+  ctx,
+  capabilityState = undefined,
+  cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
+  options = {},
+) {
   if (capabilityState && !capabilityState.configured) {
     ctx.ui.setStatus("freeflow", capabilityState.configExists ? "freeflow: config error" : "freeflow: setup needed");
     return;
@@ -489,188 +448,200 @@ export function setModeStatus(ctx, modeState, capabilityState = undefined) {
     ctx.ui.setStatus("freeflow", `freeflow: off${source}`);
     return;
   }
-  const active = [];
-  if (capabilityState?.interactionContract.effective) {
-    active.push("interaction");
-  } else if (capabilityState?.configSources?.interactionContract === "session") {
-    active.push("interaction off (session)");
-  }
-  if (capabilityState?.skills.effective) {
-    active.push(`${modeState.effectiveMode}${modeState.currentMode ? " (session)" : ""}`);
-  } else if (capabilityState?.configSources?.skillsEnabled === "session") {
-    active.push("skills off (session)");
+  if (capabilityState?.enabled === true && !hasUsableMandatoryPrompts(freeflowContext)) {
+    ctx.ui.setStatus("freeflow", "freeflow: unavailable");
+    return;
   }
-  if (capabilityState?.outputRouter.enabled) {
-    active.push("router");
+  const active = [];
+  const cognitiveRouting = capabilityState?.cognitiveRouting;
+  const cognitiveRoutingInactive =
+    cognitiveRouting?.enabled === true && cognitiveRoutingRuntime?.runtimeStatus === "inactive";
+  const cognitiveRoutingBlocked =
+    cognitiveRouting?.enabled === true &&
+    (cognitiveRouting?.blockingReason?.code === "runtime_blocked" ||
+      cognitiveRoutingRuntime?.runtimeStatus === "blocked");
+  const cognitiveRoutingActive = cognitiveRouting?.effective === true && cognitiveRoutingRuntime?.effective === true;
+  const startupSelectionSuppressesCognitiveRouting = options.startupSelectionSuppressed === true;
+  if (cognitiveRoutingInactive) {
+    active.push("cognitive inactive");
+  } else if (cognitiveRoutingBlocked) {
+    active.push(`cognitive blocked · ${cognitiveRoutingRuntime?.runtimeReason ?? "runtime_blocked"}`);
+  } else if (cognitiveRoutingActive) {
+    const profile = cognitiveRoutingRuntime.activeProfile;
+    const control =
+      cognitiveRoutingRuntime.controlMode === "manual-standard" ||
+      cognitiveRoutingRuntime.controlMode === "manual-reasoning"
+        ? "manual hold"
+        : "automatic";
+    active.push(`${profile} · ${control}`);
+  } else if (cognitiveRouting?.enabled === true) {
+    if (cognitiveRouting.blockingReason?.code === "runtime_disabled") {
+      active.push("cognitive blocked · runtime_disabled");
+    } else if (
+      cognitiveRouting.effective === true &&
+      cognitiveRoutingRuntime === undefined &&
+      options.cognitiveRoutingStartupPending === true &&
+      !startupSelectionSuppressesCognitiveRouting
+    ) {
+      const startupProfile =
+        cognitiveRouting.sessionStart?.control === "manual"
+          ? (cognitiveRouting.sessionStart.profile ?? "reasoning")
+          : "reasoning";
+      active.push(`${startupProfile} · pending`);
+    } else {
+      const reason =
+        cognitiveRouting.effective === true
+          ? (cognitiveRoutingRuntime?.blockingReason?.code ?? "runtime_inactive")
+          : (cognitiveRouting.blockingReason?.code ?? "unavailable");
+      active.push(`cognitive blocked · ${reason}`);
+    }
   }
-  ctx.ui.setStatus("freeflow", `freeflow: ${active.length > 0 ? active.join(" · ") : "idle"}`);
-}
-function modeSourceLabel(source) {
-  if (source === "local") return "personal override";
-  if (source === "repository") return "repository default";
-  return "built-in default";
-}
-function describeModeState(modeState) {
-  const configuredDefault = `configured default ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)})`;
-  if (modeState.sessionMode) {
-    return `session ${modeState.sessionMode}; ${configuredDefault}`;
+  if (capabilityState?.contextVirtualization?.effective || capabilityState?.conversationHistory?.effective) {
+    active.push("context");
   }
-  return configuredDefault;
+  ctx.ui.setStatus("freeflow", `freeflow: ${active.length > 0 ? active.join(" · ") : "active"}`);
 }
 export function skillPrompt(skill, args) {
   const trimmed = args?.trim();
   return trimmed ? `/skill:${skill}\n\n${trimmed}` : `/skill:${skill}`;
 }
-function outputRouterModeGuidance(mode, skillsEnabled = true) {
-  if (!skillsEnabled) {
-    return "Freeflow Skills are disabled: no Freeflow workflow mode is active; apply only output-router evidence guidance.";
-  }
-  if (mode === "conversation") {
-    return "conversation mode: keep routed-tool guidance soft; answer questions directly.";
-  }
-  if (mode === "strict-workflow") {
-    return "strict-workflow mode: strongest guidance; prefer exact, recoverable routed evidence for risky work.";
-  }
-  return "workflow mode: prefer routed tools for exploration and likely-large command output.";
-}
-function outputRouterContext(modeState, freeflowContext, routerConfigResult, capabilityState) {
-  const safetyNetText =
-    routerConfigResult.config.postToolRouting === "off"
-      ? ""
-      : "\n\nOutput-router config note: large native read/bash outputs may be vaulted and replaced with labeled routed output. Use freeflow_search with the output id to recover exact content.";
-  return `## Loaded Output Router Skill
-
-Mode guidance: ${outputRouterModeGuidance(modeState.effectiveMode, capabilityState.skills.effective)}${safetyNetText}
-
-\`\`\`md
-${freeflowContext.outputRouterSkill.trim()}
-\`\`\``;
-}
-function capabilityContext(capabilityState) {
-  const sessionSuffix = (source) => (source === "session" ? " (session override)" : "");
-  const interactionContract = `${capabilityState.interactionContract.effective ? "enabled" : "disabled"}${sessionSuffix(capabilityState.configSources.interactionContract)}`;
-  const skills = `${capabilityState.skills.effective ? "enabled" : "disabled"}${sessionSuffix(capabilityState.configSources.skillsEnabled)}`;
-  const outputRouter = capabilityState.outputRouter.enabled ? "enabled" : "disabled";
-  return `## Freeflow Capabilities
-
-- Interaction contract: ${interactionContract}. Configure with \`/freeflow settings\` or temporarily with \`/freeflow settings session\`; inspect with \`/freeflow status\`.
-- Skills: ${skills}. Configure with \`/freeflow settings\` or temporarily with \`/freeflow settings session\`; inspect with \`/freeflow status\`.
-- Output router: ${outputRouter}. Configure with \`/freeflow settings\` or \`/output-router\`; inspect with \`/output-router status\`.
-
-Disabled capabilities are named only for status/config awareness. Capability-specific instructions and tools are active only while that capability is enabled.`;
-}
-function hasModelFacingCapability(capabilityState) {
-  return (
-    capabilityState.interactionContract.effective ||
-    capabilityState.skills.effective ||
-    capabilityState.outputRouter.enabled
+function publicCognitiveRoutingControl(controlMode) {
+  if (controlMode === "automatic") return "automatic";
+  if (controlMode === "manual-standard" || controlMode === "manual-reasoning") return "manual";
+  return "unavailable";
+}
+function publicCognitiveRoutingProfile(activeProfile, effective) {
+  if (effective !== true) return "unavailable";
+  return activeProfile === "standard" || activeProfile === "reasoning" ? activeProfile : "unavailable";
+}
+function publicCapabilityStatus(capability) {
+  if (capability?.effective === true) return "active";
+  if (!capability) return "unavailable";
+  const blockingCode = capability.blockingReason?.code;
+  if (blockingCode && blockingCode !== "disabled") return "unavailable";
+  return "inactive";
+}
+function publicCognitiveRoutingStatus(capability, runtime) {
+  if (runtime?.runtimeStatus === "inactive") return "inactive";
+  return publicCapabilityStatus(capability);
+}
+export function freeflowRuntimeStateMessage(
+  capabilityState,
+  cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
+) {
+  const cognitiveRoutingEffective = capabilityState?.cognitiveRouting?.effective === true;
+  const profile = publicCognitiveRoutingProfile(
+    cognitiveRoutingRuntime?.activeProfile,
+    cognitiveRoutingEffective && cognitiveRoutingRuntime?.effective === true,
   );
+  const control =
+    profile === "unavailable" ? "unavailable" : publicCognitiveRoutingControl(cognitiveRoutingRuntime?.controlMode);
+  const mandatoryPromptAvailable = capabilityState?.enabled !== true || hasUsableMandatoryPrompts(freeflowContext);
+  const freeflowStatus = capabilityState?.configured
+    ? capabilityState.enabled
+      ? mandatoryPromptAvailable
+        ? "active"
+        : "unavailable"
+      : "inactive"
+    : capabilityState?.configExists
+      ? "config error"
+      : "setup needed";
+  return {
+    role: "custom",
+    customType: FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE,
+    content: [
+      "# Freeflow Runtime State",
+      "",
+      "This is extension-generated runtime state. Use it to interpret the stable Freeflow guidance.",
+      "",
+      `Freeflow: ${freeflowStatus}`,
+      "",
+      "Capabilities:",
+      `- Context Virtualization: ${publicCapabilityStatus(capabilityState?.contextVirtualization)}`,
+      `- Conversation History: ${publicCapabilityStatus(capabilityState?.conversationHistory)}`,
+      `- Cognitive Routing: ${publicCognitiveRoutingStatus(capabilityState?.cognitiveRouting, cognitiveRoutingRuntime)}`,
+      "",
+      "Cognitive Routing:",
+      `- Control: \`${control}\``,
+      `- Profile: \`${profile}\``,
+    ].join("\n"),
+    display: false,
+    details: { source: "provider-request-runtime-state" },
+  };
 }
-function modeOverlayContext(mode) {
-  if (mode === "conversation") {
-    return `
-
-## Conversation Mode Boundary
-
-Conversation mode is active and read-only.
-
-Do not call write, edit, or mutating tools. Do not create, delete, commit, push, or change repository, system, external, or durable state.
-
-A mutation request does not switch mode, and an execution skill does not override this boundary. Explain that conversation mode is read-only and ask the user to switch to workflow or strict-workflow.`;
-  }
-  if (mode === "strict-workflow") {
-    return `
-
-## Strict Workflow Overlay
-
-Strict Workflow is active. Use the adaptive Workflow, but increase decision, evidence, verification, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
-
-For work affecting security, privacy, billing, data loss, migrations, public interfaces, compatibility, deployment, or architecture:
-
-- stop for any user-owned choice or source conflict;
-- inspect the relevant risk surface before crossing the boundary;
-- select only artifacts, checkpoints, and independent review that materially reduce risk;
-- verify at the affected boundary before claiming success.
-
-Do not manufacture ceremony for low-risk, reversible work. Strict Workflow does not authorize mutation, bypass safety, or make every implementation detail a user decision.`;
-  }
-  return "";
-}
-function activeModeContext(modeState) {
-  return `## Freeflow Mode State
-
-Repository default mode: \`${modeState.repositoryDefaultMode}\` (${modeState.repositoryDefaultModeSource}).
-Personal default override: \`${modeState.personalDefaultMode ?? "none"}\`.
-Configured default mode: \`${modeState.defaultMode}\` (${modeSourceLabel(modeState.defaultModeSource)}).
-Session mode override: \`${modeState.sessionMode ?? "none"}\`.
-Resolved mode: \`${modeState.resolvedMode}\`.
-Effective Freeflow mode: \`${modeState.effectiveMode}\`.
-
-Mode behavior:
-- \`conversation\`: answer, discuss, critique, and inspect read-only; require a mode change before mutating state.
-- \`workflow\`: use the adaptive workflow for consequential or mutating work.
-- \`strict-workflow\`: use the same workflow with stronger decision, evidence, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
-
-Task type, risk classification, and direct skill calls do not change mode. Recommend another mode when useful; the user decides.
-Do not announce mode on every reply. Mention it when the user asks, configuration is discussed, or it changes the next action.${modeOverlayContext(modeState.effectiveMode)}`;
-}
-function inactiveModeContext(modeState) {
-  return `## Freeflow Mode State
-
-Repository default mode: \`${modeState.repositoryDefaultMode}\` (${modeState.repositoryDefaultModeSource}).
-Personal default override: \`${modeState.personalDefaultMode ?? "none"}\`.
-Configured default mode: \`${modeState.defaultMode}\` (${modeSourceLabel(modeState.defaultModeSource)}).
-Session mode override: \`${modeState.sessionMode ?? "none"}\`.
-Resolved mode: \`${modeState.resolvedMode}\` (inactive because Skills are disabled).
-Effective Freeflow mode: \`none\`.
-
-Freeflow workflow modes are dormant until Skills are enabled with \`/freeflow settings\`.`;
-}
-function controlPlaneContext(modeState, capabilityState) {
-  return `# Freeflow Control Plane
-
-Freeflow is enabled for this repo, but no model-facing capabilities are enabled.
-These lines are status/config awareness only; do not apply Freeflow workflow or output-router behavior.
-
-${inactiveModeContext(modeState)}
-
-${capabilityContext(capabilityState)}
-
-Use \`/freeflow settings\` to enable the Interaction Contract, Skills, or Output Router. The read-only \`freeflow_status\` diagnostic may be available so the model can answer setup/status questions.`;
-}
-export function runtimeContext(modeState, freeflowContext, routerConfigResult, capabilityState) {
-  if (!capabilityState.configured) {
+export function withoutFreeflowRuntimeState(messages) {
+  return (Array.isArray(messages) ? messages : []).filter(
+    (message) =>
+      message?.customType !== FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE &&
+      message?.customType !== COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE,
+  );
+}
+function lastUserMessageIndex(messages) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "user") return index;
+  }
+  return -1;
+}
+function insertRuntimeStateBeforeLatestUser(messages, runtimeState) {
+  const latestUserIndex = lastUserMessageIndex(messages);
+  if (latestUserIndex < 0) return [...messages, runtimeState];
+  return [...messages.slice(0, latestUserIndex), runtimeState, ...messages.slice(latestUserIndex)];
+}
+export function withFreeflowRuntimeState(
+  messages,
+  capabilityState,
+  cognitiveRoutingRuntime = undefined,
+  freeflowContext = undefined,
+  options = {},
+) {
+  const source = Array.isArray(messages) ? messages : [];
+  const runtimeState = freeflowRuntimeStateMessage(capabilityState, cognitiveRoutingRuntime, freeflowContext);
+  const runtimeStateMessages = source.filter(
+    (message) =>
+      message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE ||
+      message?.customType === COGNITIVE_ROUTING_RUNTIME_STATE_MESSAGE_TYPE,
+  );
+  const withoutRuntimeState = withoutFreeflowRuntimeState(source);
+  const expectedRuntimeStateIndex = lastUserMessageIndex(withoutRuntimeState);
+  const runtimeStateIndex = source.findIndex((message) => message?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE);
+  const unchanged =
+    options.force !== true &&
+    runtimeStateMessages.length === 1 &&
+    runtimeStateMessages[0]?.customType === FREEFLOW_RUNTIME_STATE_MESSAGE_TYPE &&
+    runtimeStateMessages[0]?.content === runtimeState.content &&
+    runtimeStateIndex === (expectedRuntimeStateIndex < 0 ? withoutRuntimeState.length : expectedRuntimeStateIndex);
+  if (unchanged) return source;
+  return insertRuntimeStateBeforeLatestUser(withoutRuntimeState, runtimeState);
+}
+export function runtimeContext(freeflowContext, capabilityState) {
+  if (
+    capabilityState?.configured !== true ||
+    capabilityState?.enabled !== true ||
+    !hasUsableMandatoryPrompts(freeflowContext)
+  ) {
     return "";
   }
-  if (!capabilityState.enabled) {
-    return `# Freeflow Disabled
-
-Freeflow is disabled by \`.freeflow/config.json\` for this repo. Do not apply the Freeflow Interaction Contract, workflow, or output-router behavior unless the user re-enables Freeflow with \`/freeflow enable\` or \`/freeflow settings\`.
-
-These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.`;
-  }
-  if (!hasModelFacingCapability(capabilityState)) {
-    return controlPlaneContext(modeState, capabilityState);
-  }
-  const modeText = capabilityState.skills.effective ? activeModeContext(modeState) : inactiveModeContext(modeState);
-  const interactionContractText = capabilityState.interactionContract.effective
-    ? `\n\n${freeflowContext.interactionContract.trim()}`
-    : "";
-  const routerText =
-    capabilityState.outputRouter.enabled && routerConfigResult.config.enabled
-      ? `\n\n${outputRouterContext(modeState, freeflowContext, routerConfigResult, capabilityState)}`
-      : "";
-  return `# Freeflow Runtime Context
-
-Freeflow Pi extension loaded this before the agent turn.
-Runtime delivery: confirmed for this Pi \`before_agent_start\` invocation.
-These instructions are context-loading only. They do not override user instructions, repo instructions, or host safety and approval policy.
-
-${modeText}
-
-${capabilityContext(capabilityState)}${interactionContractText}${routerText}
-
-This Pi extension loads enabled runtime context before every agent turn and routes commands only; it does not enforce policy, block tools, grant permissions, or create repo-local hooks.`;
+  const blocks = [freeflowContext.corePrompt.trim(), freeflowContext.interactionContractPrompt.trim()];
+  if (
+    capabilityState.cognitiveRouting?.effective === true &&
+    isPromptAvailable(freeflowContext.cognitiveRoutingPrompt)
+  ) {
+    blocks.push(freeflowContext.cognitiveRoutingPrompt.trim());
+  }
+  if (
+    capabilityState.contextVirtualization?.effective === true &&
+    isPromptAvailable(freeflowContext.contextVirtualizationPrompt)
+  ) {
+    blocks.push(freeflowContext.contextVirtualizationPrompt.trim());
+  }
+  if (
+    capabilityState.conversationHistory?.effective === true &&
+    isPromptAvailable(freeflowContext.conversationHistoryPrompt)
+  ) {
+    blocks.push(freeflowContext.conversationHistoryPrompt.trim());
+  }
+  return blocks.filter(Boolean).join("\n\n");
 }
 export async function setSessionCoreOverride(key, value, ctx, pi) {
   if (!SESSION_CORE_KEYS.has(key)) {
@@ -693,106 +664,22 @@ export async function setSessionCoreOverride(key, value, ctx, pi) {
   pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: { ...currentSessionOverrides } });
   return {
     changed: true,
-    reloadRequired: key === "enabled" || key === "skillsEnabled",
+    reloadRequired: key === "enabled",
     sessionOverrides: { ...currentSessionOverrides },
-    capabilityState: await readCapabilityState(ctx.cwd),
+    capabilityState: await readCapabilityState(ctx.cwd, ctx, pi?.host),
   };
 }
 export async function resetSessionOverrides(ctx, pi) {
   const hadCoreOverrides = Object.keys(currentSessionOverrides).length > 0;
-  const reloadRequired =
-    Object.hasOwn(currentSessionOverrides, "enabled") || Object.hasOwn(currentSessionOverrides, "skillsEnabled");
-  const hadModeOverride = VALID_MODES.has(currentModeOverride);
+  const reloadRequired = Object.hasOwn(currentSessionOverrides, "enabled");
   if (hadCoreOverrides) {
     currentSessionOverrides = {};
     pi?.appendEntry?.(SESSION_OVERRIDES_ENTRY, { overrides: {} });
   }
-  if (hadModeOverride) {
-    await setSessionMode(null, ctx, pi);
-  }
   return {
-    changed: hadCoreOverrides || hadModeOverride,
+    changed: hadCoreOverrides,
     reloadRequired,
     sessionOverrides: { ...currentSessionOverrides },
-    modeState: await readModeState(ctx.cwd),
+    capabilityState: await readCapabilityState(ctx.cwd, ctx, pi?.host),
   };
 }
-export async function setSessionMode(mode, ctx, pi) {
-  const nextMode = mode === "default" || mode === "reset" || mode === null ? null : mode;
-  if (nextMode !== null && !VALID_MODES.has(nextMode)) {
-    throw new Error(`Invalid Freeflow mode: ${String(mode)}`);
-  }
-  currentModeOverride = nextMode;
-  pi?.appendEntry?.(MODE_STATE_ENTRY, { currentMode: nextMode });
-  return readModeState(ctx.cwd);
-}
-export async function handleModeCommand(args, ctx, pi) {
-  const arg = args?.trim();
-  const capabilityState = await readCapabilityState(ctx.cwd);
-  const inactiveModeState = await readModeState(ctx.cwd);
-  if (!capabilityState.configured) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      "Freeflow is installed but this repo is not set up. Run /setup-freeflow before changing mode.",
-      "warning",
-    );
-    return { changed: false, error: "not_configured" };
-  }
-  if (!capabilityState.enabled) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      "Freeflow is disabled for this repo. Use /freeflow enable or /freeflow settings to re-enable it.",
-      "warning",
-    );
-    return { changed: false, error: "freeflow_disabled" };
-  }
-  if (!capabilityState.skills.effective) {
-    setModeStatus(ctx, inactiveModeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow modes are inactive because Skills are disabled. Configured default mode: ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}). Enable Skills in /freeflow settings before changing mode.`,
-      "warning",
-    );
-    return { changed: false, error: "skills_disabled" };
-  }
-  if (VALID_MODES.has(arg)) {
-    if (inactiveModeState.effectiveMode === arg) {
-      setModeStatus(ctx, inactiveModeState, capabilityState);
-      const message = inactiveModeState.sessionMode
-        ? `Freeflow is already in ${arg} mode for this Pi session. No session entry was added. Configured default remains ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}).`
-        : `Freeflow is already in ${arg} mode from the configured default (${modeSourceLabel(inactiveModeState.defaultModeSource)}). No session override was created.`;
-      ctx.ui.notify(message, "info");
-      return { changed: false, modeState: inactiveModeState };
-    }
-    const modeState = await setSessionMode(arg, ctx, pi);
-    setModeStatus(ctx, modeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow mode is now ${modeState.effectiveMode} for this Pi session. Stored in Pi session history; .freeflow/local.json and .freeflow/config.json were not changed. Configured default remains ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)}).`,
-      "info",
-    );
-    return { changed: true, modeState };
-  }
-  if (RESET_MODE_ARGS.has(arg) || arg === "default") {
-    if (!inactiveModeState.sessionMode) {
-      setModeStatus(ctx, inactiveModeState, capabilityState);
-      ctx.ui.notify(
-        `Freeflow is already using the configured default: ${inactiveModeState.defaultMode} (${modeSourceLabel(inactiveModeState.defaultModeSource)}). No session override is active.`,
-        "info",
-      );
-      return { changed: false, modeState: inactiveModeState };
-    }
-    const modeState = await setSessionMode(null, ctx, pi);
-    setModeStatus(ctx, modeState, capabilityState);
-    ctx.ui.notify(
-      `Freeflow mode reset to configured default: ${modeState.defaultMode} (${modeSourceLabel(modeState.defaultModeSource)}). Session override cleared; .freeflow/local.json and .freeflow/config.json were not changed.`,
-      "info",
-    );
-    return { changed: true, modeState };
-  }
-  const modeState = await readModeState(ctx.cwd);
-  setModeStatus(ctx, modeState, capabilityState);
-  ctx.ui.notify(
-    `Freeflow mode is ${modeState.effectiveMode} (${describeModeState(modeState)}). Use /freeflow mode conversation, /freeflow mode workflow, /freeflow mode strict-workflow, or /freeflow mode reset.`,
-    "info",
-  );
-  return { changed: false, modeState, error: arg ? "invalid_mode" : undefined };
-}