@hassangameryt/freeflow 0.7.0 → 0.7.1

package/.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
     {
       "name": "freeflow",
       "description": "Feedback-based control for coding agents.",
-      "version": "0.7.0",
+      "version": "0.7.1",
       "category": "development",
       "source": "./",
       "author": {

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "freeflow",
   "description": "Freeflow gives coding agents an Interaction Contract, adaptive Workflow, focused methods, and durable task memory.",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "author": {
     "name": "Hassan Mohiddin"
   },
@@ -9,6 +9,7 @@
   "repository": "https://github.com/hassan-mohiddin/freeflow",
   "license": "MIT",
   "skills": "./skills/",
+  "hooks": "./hooks/claude/hooks.json",
   "keywords": [
     "workflow",
     "skills",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "freeflow",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"
@@ -21,7 +21,7 @@
     "claude"
   ],
   "skills": "./skills/",
-  "hooks": "./hooks/hooks.json",
+  "hooks": "./hooks/codex/hooks.json",
   "interface": {
     "displayName": "Freeflow",
     "shortDescription": "Feedback-based control for coding agents.",

package/.cursor-plugin/plugin.json

@@ -0,0 +1,25 @@
+{
+  "name": "freeflow",
+  "description": "Feedback-based control system for coding agents.",
+  "version": "0.7.1",
+  "author": {
+    "name": "Hassan Mohiddin"
+  },
+  "homepage": "https://github.com/hassan-mohiddin/freeflow",
+  "repository": "https://github.com/hassan-mohiddin/freeflow",
+  "license": "MIT",
+  "skills": "./skills/",
+  "hooks": "./hooks/cursor/hooks.json",
+  "logo": "assets/freeflow-plugin-icon-transparent.png",
+  "keywords": [
+    "workflow",
+    "skills",
+    "agents",
+    "feedback-loop",
+    "task-memory",
+    "planning",
+    "verification",
+    "review",
+    "cursor"
+  ]
+}

package/README.md

@@ -60,12 +60,18 @@ Freeflow is one package with different host boundaries:
 
 | Host | Freeflow support | Cognitive Routing |
 | --- | --- | --- |
-| Codex | Shared skills and lifecycle hook | Not available; Pi/PiFlow capabilities are not delivered |
-| Claude Code | Shared skills and lifecycle hook | Not available; Pi/PiFlow capabilities are not delivered |
+| Codex | Shared skills and Codex `SessionStart` hook | Not available; Pi/PiFlow capabilities are not delivered |
+| Claude Code | Shared skills and Claude Code `SessionStart` hook | Not available; Pi/PiFlow capabilities are not delivered |
+| Gemini CLI | Gemini extension manifest, shared skills, and Gemini `SessionStart` hook | Not available; Pi/PiFlow capabilities are not delivered |
+| Cursor | Agent Plugins 1.0 skills plus Cursor-specific hook delivery | Not available; Pi/PiFlow capabilities are not delivered |
+| GitHub Copilot / VS Code | Agent Plugins 1.0 skills plus Copilot-specific hook delivery | Not available; Pi/PiFlow capabilities are not delivered |
+| Kiro | Agent Plugins 1.0 Power and shared skills | Not available; no Kiro-specific runtime adapter is claimed |
+| OpenCode v2 | Canonical `skills/` through OpenCode’s project skill source | Not available; skills-only support |
+| Hermes Agent | Agent Plugins 1.0 package and canonical skills | Not available; skills-only support |
 | Pi | Shared skills, Pi extension, optional context capabilities, and native host controls | Available when configured and the official model-state APIs are present |
 | PiFlow | Freeflow package hosted by the separate PiFlow distribution | Available when configured |
 
-Freeflow owns workflow policy, prompt fragments, skills, capabilities, and the Pi extension. Each host owns its launch, package installation, session state, updates, and native model-state control; PiFlow remains a supported host integration.
+Freeflow owns workflow policy, portable prompt fragments, the 25-skill distribution kernel, host adapters, Pi/PiFlow capabilities, and the Pi extension. Each host owns its launch, package installation, session state, updates, and native model-state control; PiFlow remains a supported host integration.
 
 ## Capabilities
 
@@ -106,6 +112,24 @@ Trust the Freeflow hook from `/hooks`, then start a new session.
 /reload-plugins
 ```
 
+### Gemini CLI
+
+```bash
+gemini extensions install https://github.com/hassan-mohiddin/freeflow
+```
+
+Restart Gemini CLI after installation or updates. The extension uses the root `gemini-extension.json`, shared `skills/`, and its Gemini-specific `SessionStart` hook adapter.
+
+### Cursor, GitHub Copilot, VS Code, Kiro, OpenCode, and Hermes Agent
+
+These hosts consume the root Agent Plugins 1.0 manifest and the same `skills/` directory. Cursor also reads `.cursor-plugin/plugin.json` for its host-specific hook surface; GitHub Copilot and VS Code read the `com.github.copilot/` extension namespace. Install from each host’s documented plugin source or marketplace UI. For Copilot CLI, the direct repository form is:
+
+```bash
+copilot plugin install hassan-mohiddin/freeflow
+```
+
+VS Code provides **Chat: Install Plugin From Source**. Kiro exposes compatible Agent Plugins as Powers and can import a GitHub source through its Powers UI. OpenCode v2 can add the checkout or package’s `skills/` directory to the documented `skills` array in `opencode.json`; it does not receive a native Freeflow plugin runtime. Hermes can install the root portable package with `hermes plugins install hassan-mohiddin/freeflow --no-enable`, then enable it with `hermes plugins enable freeflow`, or use its documented skills source workflow. A host’s install/trust UI and marketplace availability are external to this repository’s deterministic checks.
+
 ### Pi
 
 ```bash
@@ -178,6 +202,8 @@ Read the full [System Prompt Architecture](https://github.com/hassan-mohiddin/fr
 Freeflow is explicit about what its checks prove:
 
 - deterministic checks prove structure, assembly, package boundaries, and selected delivery behavior;
+- host-manifest and adapter checks prove the Agent Plugins 1.0, Gemini, Cursor, and Copilot/VS Code package shapes, not native host dispatch;
+- OpenCode and Hermes compatibility checks cover the canonical Agent Skills/Agent Plugins package shape, not native host plugin APIs or runtime prompt delivery;
 - release evidence is versioned and records source, checks, artifacts, deferred evidence, and limits;
 - local installation does not prove remote host installation or registry propagation;
 - deterministic skill/runtime checks do not prove model behavior or universal skill readiness;

package/com.github.copilot/hooks/hooks.json

@@ -0,0 +1,11 @@
+{
+  "version": 1,
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "node \"${PLUGIN_ROOT}/hooks/adapters/copilot-session-start.mjs\" SessionStart"
+      }
+    ]
+  }
+}

package/gemini-extension.json

@@ -0,0 +1,5 @@
+{
+  "name": "freeflow",
+  "version": "0.7.1",
+  "description": "Feedback-based control system for coding agents."
+}

package/hooks/adapters/claude-session-start.mjs

@@ -0,0 +1,16 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["SessionStart"],
+    getWorkspaceCwd: (input) => input.cwd || process.cwd(),
+    formatOutput: ({ eventName, additionalContext }) => ({
+      hookSpecificOutput: {
+        hookEventName: eventName,
+        additionalContext,
+      },
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/adapters/codex-session-start.mjs

@@ -0,0 +1,16 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["SessionStart"],
+    getWorkspaceCwd: (input) => input.cwd || process.cwd(),
+    formatOutput: ({ eventName, additionalContext }) => ({
+      hookSpecificOutput: {
+        hookEventName: eventName,
+        additionalContext,
+      },
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/adapters/copilot-session-start.mjs

@@ -0,0 +1,13 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["SessionStart"],
+    getWorkspaceCwd: (input) => input.cwd || process.cwd(),
+    formatOutput: ({ additionalContext }) => ({
+      additionalContext,
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/adapters/cursor-session-start.mjs

@@ -0,0 +1,13 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["sessionStart", "SessionStart"],
+    getWorkspaceCwd: (input) => input.workspace_roots?.[0] || input.cwd || process.cwd(),
+    formatOutput: ({ additionalContext }) => ({
+      additional_context: additionalContext,
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/adapters/gemini-session-start.mjs

@@ -0,0 +1,15 @@
+import { isMainModule, runSafely, runSessionStartAdapter } from "../shared/runtime-context.mjs";
+
+export function main() {
+  runSessionStartAdapter({
+    eventNames: ["SessionStart"],
+    getWorkspaceCwd: (input) => input.cwd || process.cwd(),
+    formatOutput: ({ additionalContext }) => ({
+      hookSpecificOutput: {
+        additionalContext,
+      },
+    }),
+  });
+}
+
+if (isMainModule(import.meta.url)) runSafely(main);

package/hooks/claude/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Load Freeflow core runtime context in Claude Code.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/adapters/claude-session-start.mjs\" SessionStart",
+            "timeout": 5,
+            "statusMessage": "Loading Freeflow context"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/codex/hooks.json

@@ -0,0 +1,18 @@
+{
+  "description": "Load Freeflow core runtime context in Codex.",
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${PLUGIN_ROOT}/hooks/adapters/codex-session-start.mjs\" SessionStart",
+            "timeout": 5,
+            "statusMessage": "Loading Freeflow context"
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/cursor/hooks.json

@@ -0,0 +1,9 @@
+{
+  "hooks": {
+    "sessionStart": [
+      {
+        "command": "node hooks/adapters/cursor-session-start.mjs SessionStart"
+      }
+    ]
+  }
+}

package/hooks/freeflow-runtime-context.mjs

@@ -1,218 +1,6 @@
 #!/usr/bin/env node
 
-import fs from "node:fs";
-import path from "node:path";
-import process from "node:process";
-import { fileURLToPath } from "node:url";
+import { main } from "./adapters/codex-session-start.mjs";
+import { runSafely } from "./shared/runtime-context.mjs";
 
-const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
-const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "..");
-
-function readStdinJson() {
-  const raw = fs.readFileSync(0, "utf8").trim();
-  if (!raw) return { input: {}, raw: "" };
-
-  try {
-    return { input: JSON.parse(raw), raw };
-  } catch {
-    return { input: {}, raw };
-  }
-}
-
-function readText(filePath) {
-  try {
-    const text = fs.readFileSync(filePath, "utf8").trim();
-    return text || null;
-  } catch {
-    return null;
-  }
-}
-
-function findWorkspaceRoot(cwd) {
-  let current = path.resolve(cwd || process.cwd());
-
-  while (true) {
-    if (fs.existsSync(path.join(current, ".git"))) return current;
-
-    const parent = path.dirname(current);
-    if (parent === current) return path.resolve(cwd || process.cwd());
-    current = parent;
-  }
-}
-
-function loadRuntimeContext() {
-  const corePrompt = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "core.md"));
-  const interactionContract = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "interaction-contract.md"));
-
-  if (!corePrompt || !interactionContract) {
-    throw new Error("Freeflow core runtime prompt files are missing.");
-  }
-
-  return { corePrompt, interactionContract };
-}
-
-function readConfig(root) {
-  const repository = readConfigLayer(path.join(root, ".freeflow", "config.json"), isValidSetupConfig);
-  const local = readConfigLayer(path.join(root, ".freeflow", "local.json"), isValidLocalConfig);
-  const localValid = !local.exists || local.valid;
-  const configured = repository.valid && localValid;
-  const core = resolveCoreConfig(repository.valid ? repository.parsed : {}, local.valid ? local.parsed : {});
-  const enabled = configured && core.config.enabled;
-
-  return {
-    exists: repository.exists,
-    valid: configured,
-    configured,
-    repositoryValid: repository.valid,
-    localExists: local.exists,
-    localValid,
-    error: repository.valid ? local.error : repository.error,
-    enabled,
-    contextVirtualizationEnabled: enabled && core.config.contextVirtualization,
-    conversationHistoryEnabled: enabled && core.config.conversationHistory,
-  };
-}
-
-function readConfigLayer(filePath, validate) {
-  if (!fs.existsSync(filePath)) {
-    return { path: filePath, exists: false, valid: false, parsed: {}, error: null };
-  }
-
-  try {
-    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
-    const error = validate(parsed);
-    return {
-      path: filePath,
-      exists: true,
-      valid: error === null,
-      parsed: error === null ? parsed : {},
-      error,
-    };
-  } catch (error) {
-    return {
-      path: filePath,
-      exists: true,
-      valid: false,
-      parsed: {},
-      error: error instanceof Error ? error.message : String(error),
-    };
-  }
-}
-
-function isRecord(value) {
-  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-
-function validateCoreConfigFields(value) {
-  if (Object.hasOwn(value, "enabled") && typeof value.enabled !== "boolean") {
-    return "enabled must be a boolean";
-  }
-  if (Object.hasOwn(value, "contextVirtualization") && typeof value.contextVirtualization !== "boolean") {
-    return "contextVirtualization must be a boolean";
-  }
-  if (Object.hasOwn(value, "conversationHistory") && typeof value.conversationHistory !== "boolean") {
-    return "conversationHistory must be a boolean";
-  }
-  return null;
-}
-
-function isValidSetupConfig(value) {
-  if (!isRecord(value)) return "repository config must be a JSON object";
-
-  const allowedKeys = new Set([
-    "enabled",
-    "contextVirtualization",
-    "conversationHistory",
-    "outputRouter",
-    "observedRouting",
-    "scriptTransform",
-    "cognitiveRouting",
-  ]);
-  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
-    return "repository config contains unsupported top-level keys";
-  }
-
-  const coreError = validateCoreConfigFields(value);
-  if (coreError) return coreError;
-
-  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
-    if (Object.hasOwn(value, key) && !isRecord(value[key])) return `${key} must be an object`;
-  }
-  return null;
-}
-
-function isValidLocalConfig(value) {
-  if (!isRecord(value)) return "local config must be a JSON object";
-
-  const allowedKeys = new Set([
-    "enabled",
-    "processing",
-    "cognitiveRouting",
-    "contextVirtualization",
-    "conversationHistory",
-  ]);
-  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
-    return "local config contains unsupported top-level keys";
-  }
-  return validateCoreConfigFields(value);
-}
-
-function resolveLayeredValue(repository, local, key, fallback) {
-  if (Object.hasOwn(local, key)) return local[key];
-  if (Object.hasOwn(repository, key)) return repository[key];
-  return fallback;
-}
-
-function resolveCoreConfig(repository, local) {
-  return {
-    config: {
-      enabled: resolveLayeredValue(repository, local, "enabled", true),
-      contextVirtualization: resolveLayeredValue(repository, local, "contextVirtualization", false),
-      conversationHistory: resolveLayeredValue(repository, local, "conversationHistory", false),
-    },
-  };
-}
-
-function runtimeStateContext() {
-  return ["# Freeflow Runtime State", "", "Freeflow: active"].join("\n");
-}
-
-function renderSessionStart(config) {
-  if (!config.valid || !config.enabled) return "";
-
-  const { corePrompt, interactionContract } = loadRuntimeContext();
-  return [corePrompt.trim(), interactionContract.trim(), runtimeStateContext()].filter(Boolean).join("\n\n");
-}
-
-function shouldHandle(eventName) {
-  if (process.env.FREEFLOW_DISABLE_RUNTIME_CONTEXT === "1") return false;
-  return eventName === "SessionStart";
-}
-
-function emitAdditionalContext(eventName, additionalContext) {
-  process.stdout.write(
-    `${JSON.stringify({
-      hookSpecificOutput: {
-        hookEventName: eventName,
-        additionalContext,
-      },
-    })}\n`,
-  );
-}
-
-function main() {
-  const { input, raw } = readStdinJson();
-  const eventName = process.argv[2] || input.hook_event_name || "";
-
-  if ((!raw && !eventName) || !shouldHandle(eventName)) return;
-
-  const root = findWorkspaceRoot(input.cwd || process.cwd());
-  const additionalContext = renderSessionStart(readConfig(root));
-  if (additionalContext.trim()) emitAdditionalContext(eventName, additionalContext);
-}
-
-try {
-  main();
-} catch (error) {
-  process.stderr.write(`Freeflow runtime context hook skipped: ${error.message}\n`);
-}
+runSafely(main);

package/hooks/hooks.json

@@ -1,15 +1,14 @@
 {
-  "description": "Load Freeflow core runtime context.",
+  "description": "Load Freeflow core runtime context in Gemini CLI.",
   "hooks": {
     "SessionStart": [
       {
-        "matcher": "startup|resume|clear|compact",
         "hooks": [
           {
             "type": "command",
-            "command": "node \"${CLAUDE_PLUGIN_ROOT:-${PLUGIN_ROOT}}/hooks/freeflow-runtime-context.mjs\" SessionStart",
-            "timeout": 5,
-            "statusMessage": "Loading Freeflow context"
+            "name": "freeflow-runtime-context",
+            "command": "node \"${extensionPath}/hooks/adapters/gemini-session-start.mjs\" SessionStart",
+            "timeout": 5000
           }
         ]
       }

package/hooks/shared/runtime-context.mjs

@@ -0,0 +1,210 @@
+import fs from "node:fs";
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const SCRIPT_DIR = path.dirname(fileURLToPath(import.meta.url));
+export const PLUGIN_ROOT = path.resolve(SCRIPT_DIR, "../..");
+
+export function readHookInput() {
+  const raw = fs.readFileSync(0, "utf8").trim();
+  if (!raw) return { input: {}, raw: "" };
+
+  try {
+    return { input: JSON.parse(raw), raw };
+  } catch {
+    return { input: {}, raw };
+  }
+}
+
+function readText(filePath) {
+  try {
+    const text = fs.readFileSync(filePath, "utf8").trim();
+    return text || null;
+  } catch {
+    return null;
+  }
+}
+
+export function findWorkspaceRoot(cwd) {
+  let current = path.resolve(cwd || process.cwd());
+
+  while (true) {
+    if (fs.existsSync(path.join(current, ".git"))) return current;
+
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(cwd || process.cwd());
+    current = parent;
+  }
+}
+
+function readConfigLayer(filePath, validate) {
+  if (!fs.existsSync(filePath)) {
+    return { exists: false, valid: false, parsed: {}, error: null };
+  }
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8"));
+    const error = validate(parsed);
+    return {
+      exists: true,
+      valid: error === null,
+      parsed: error === null ? parsed : {},
+      error,
+    };
+  } catch (error) {
+    return {
+      exists: true,
+      valid: false,
+      parsed: {},
+      error: error instanceof Error ? error.message : String(error),
+    };
+  }
+}
+
+function isRecord(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function validateCoreConfigFields(value) {
+  if (Object.hasOwn(value, "enabled") && typeof value.enabled !== "boolean") {
+    return "enabled must be a boolean";
+  }
+  if (Object.hasOwn(value, "contextVirtualization") && typeof value.contextVirtualization !== "boolean") {
+    return "contextVirtualization must be a boolean";
+  }
+  if (Object.hasOwn(value, "conversationHistory") && typeof value.conversationHistory !== "boolean") {
+    return "conversationHistory must be a boolean";
+  }
+  return null;
+}
+
+function isValidSetupConfig(value) {
+  if (!isRecord(value)) return "repository config must be a JSON object";
+
+  const allowedKeys = new Set([
+    "enabled",
+    "contextVirtualization",
+    "conversationHistory",
+    "outputRouter",
+    "observedRouting",
+    "scriptTransform",
+    "cognitiveRouting",
+  ]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return "repository config contains unsupported top-level keys";
+  }
+
+  const coreError = validateCoreConfigFields(value);
+  if (coreError) return coreError;
+
+  for (const key of ["outputRouter", "observedRouting", "scriptTransform"]) {
+    if (Object.hasOwn(value, key) && !isRecord(value[key])) return `${key} must be an object`;
+  }
+  return null;
+}
+
+function isValidLocalConfig(value) {
+  if (!isRecord(value)) return "local config must be a JSON object";
+
+  const allowedKeys = new Set([
+    "enabled",
+    "processing",
+    "cognitiveRouting",
+    "contextVirtualization",
+    "conversationHistory",
+  ]);
+  if (!Object.keys(value).every((key) => allowedKeys.has(key))) {
+    return "local config contains unsupported top-level keys";
+  }
+  return validateCoreConfigFields(value);
+}
+
+function resolveLayeredValue(repository, local, key, fallback) {
+  if (Object.hasOwn(local, key)) return local[key];
+  if (Object.hasOwn(repository, key)) return repository[key];
+  return fallback;
+}
+
+function resolveCoreConfig(repository, local) {
+  return {
+    enabled: resolveLayeredValue(repository, local, "enabled", true),
+    contextVirtualization: resolveLayeredValue(repository, local, "contextVirtualization", false),
+    conversationHistory: resolveLayeredValue(repository, local, "conversationHistory", false),
+  };
+}
+
+export function readConfig(root) {
+  const repository = readConfigLayer(path.join(root, ".freeflow", "config.json"), isValidSetupConfig);
+  const local = readConfigLayer(path.join(root, ".freeflow", "local.json"), isValidLocalConfig);
+  const localValid = !local.exists || local.valid;
+  const configured = repository.valid && localValid;
+  const core = resolveCoreConfig(repository.valid ? repository.parsed : {}, local.valid ? local.parsed : {});
+  const enabled = configured && core.enabled;
+
+  return {
+    exists: repository.exists,
+    valid: configured,
+    configured,
+    repositoryValid: repository.valid,
+    localExists: local.exists,
+    localValid,
+    error: repository.valid ? local.error : repository.error,
+    enabled,
+    contextVirtualizationEnabled: enabled && core.contextVirtualization,
+    conversationHistoryEnabled: enabled && core.conversationHistory,
+  };
+}
+
+function loadRuntimeContext() {
+  const corePrompt = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "core.md"));
+  const interactionContract = readText(path.join(PLUGIN_ROOT, "runtime", "prompts", "interaction-contract.md"));
+
+  if (!corePrompt || !interactionContract) {
+    throw new Error("Freeflow core runtime prompt files are missing.");
+  }
+
+  return { corePrompt, interactionContract };
+}
+
+function runtimeStateContext() {
+  return ["# Freeflow Runtime State", "", "Freeflow: active"].join("\n");
+}
+
+export function renderRuntimeContext(root) {
+  const config = readConfig(root);
+  if (!config.valid || !config.enabled) return "";
+
+  const { corePrompt, interactionContract } = loadRuntimeContext();
+  return [corePrompt, interactionContract, runtimeStateContext()].filter(Boolean).join("\n\n");
+}
+
+export function emitHookOutput(output) {
+  process.stdout.write(`${JSON.stringify(output)}\n`);
+}
+
+export function runSessionStartAdapter({ eventNames, getWorkspaceCwd, formatOutput }) {
+  const { input, raw } = readHookInput();
+  const eventName = process.argv[2] || input.hook_event_name || "";
+  if ((!raw && !eventName) || process.env.FREEFLOW_DISABLE_RUNTIME_CONTEXT === "1") return;
+  if (!eventNames.includes(eventName)) return;
+
+  const root = findWorkspaceRoot(getWorkspaceCwd(input));
+  const additionalContext = renderRuntimeContext(root);
+  if (additionalContext.trim()) {
+    emitHookOutput(formatOutput({ eventName, input, additionalContext }));
+  }
+}
+
+export function runSafely(run) {
+  try {
+    run();
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    process.stderr.write(`Freeflow runtime context hook skipped: ${message}\n`);
+  }
+}
+
+export function isMainModule(metaUrl) {
+  return process.argv[1] && pathToFileURL(path.resolve(process.argv[1])).href === metaUrl;
+}

package/hooks/tests/check-host-adapters.test.mjs

@@ -0,0 +1,82 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+const repoRoot = resolve(import.meta.dirname, "../..");
+const adapters = {
+  legacy: ["hooks/freeflow-runtime-context.mjs", "hookSpecificOutput.additionalContext"],
+  claude: ["hooks/adapters/claude-session-start.mjs", "hookSpecificOutput.additionalContext"],
+  codex: ["hooks/adapters/codex-session-start.mjs", "hookSpecificOutput.additionalContext"],
+  gemini: ["hooks/adapters/gemini-session-start.mjs", "hookSpecificOutput.additionalContext"],
+  copilot: ["hooks/adapters/copilot-session-start.mjs", "additionalContext"],
+  cursor: ["hooks/adapters/cursor-session-start.mjs", "additional_context"],
+};
+
+function createWorkspace(config = "{}\n") {
+  const root = mkdtempSync(join(tmpdir(), "freeflow-host-adapter-"));
+  mkdirSync(join(root, ".freeflow"), { recursive: true });
+  writeFileSync(join(root, ".freeflow", "config.json"), config, "utf8");
+  return root;
+}
+
+function runAdapter(relativePath, workspace, input, event = "SessionStart") {
+  const result = spawnSync(process.execPath, [join(repoRoot, relativePath), event], {
+    cwd: repoRoot,
+    input: `${JSON.stringify(input)}\n`,
+    encoding: "utf8",
+  });
+  assert.equal(result.status, 0, `${relativePath} stderr: ${result.stderr}`);
+  assert.equal(result.stderr, "", `${relativePath} should not log on the happy path`);
+  return result.stdout.trim() ? JSON.parse(result.stdout) : undefined;
+}
+
+test("host adapters share rendered mandatory context but emit host-native envelopes", () => {
+  const workspace = createWorkspace();
+  const outputs = {};
+  for (const [host, [relativePath]] of Object.entries(adapters)) {
+    const input =
+      host === "cursor"
+        ? { hook_event_name: "sessionStart", workspace_roots: [workspace] }
+        : { hook_event_name: "SessionStart", cwd: workspace };
+    outputs[host] = runAdapter(relativePath, workspace, input, host === "cursor" ? "sessionStart" : "SessionStart");
+    assert.ok(outputs[host], `${host} should emit context`);
+  }
+
+  const legacyContext = outputs.legacy.hookSpecificOutput.additionalContext;
+  for (const host of ["claude", "codex", "gemini"]) {
+    assert.equal(outputs[host].hookSpecificOutput.additionalContext, legacyContext);
+  }
+  assert.deepEqual(Object.keys(outputs.copilot).sort(), ["additionalContext"]);
+  assert.equal(outputs.copilot.additionalContext, legacyContext);
+  assert.equal(outputs.copilot.hookSpecificOutput, undefined);
+  assert.equal(outputs.cursor.additional_context, legacyContext);
+  assert.equal(outputs.cursor.hookSpecificOutput, undefined);
+  assert.match(legacyContext, /# Freeflow Stable Guidance/);
+  assert.match(legacyContext, /# Freeflow Interaction Contract/);
+  assert.match(legacyContext, /Freeflow: active/);
+  assert.doesNotMatch(legacyContext, /Cognitive Routing/);
+});
+
+test("host adapters stay inert for disabled, invalid, and unsupported lifecycle inputs", () => {
+  const disabledWorkspace = createWorkspace('{"enabled":false}\n');
+  const invalidWorkspace = createWorkspace('{"enabled":"no"}\n');
+  for (const [host, [relativePath]] of Object.entries(adapters)) {
+    const input =
+      host === "cursor"
+        ? { hook_event_name: "sessionStart", workspace_roots: [disabledWorkspace] }
+        : { hook_event_name: "SessionStart", cwd: disabledWorkspace };
+    assert.equal(
+      runAdapter(relativePath, disabledWorkspace, input, host === "cursor" ? "sessionStart" : "SessionStart"),
+      undefined,
+    );
+    const invalidInput = { ...input, cwd: invalidWorkspace, workspace_roots: [invalidWorkspace] };
+    assert.equal(
+      runAdapter(relativePath, invalidWorkspace, invalidInput, host === "cursor" ? "sessionStart" : "SessionStart"),
+      undefined,
+    );
+    assert.equal(runAdapter(relativePath, disabledWorkspace, input, "UserPromptSubmit"), undefined);
+  }
+});

package/hooks/tests/check-runtime-context-hook.sh

@@ -3,7 +3,11 @@ set -euo pipefail
 
 ROOT_DIR="$(CDPATH='' cd -- "$(dirname -- "$0")/../.." && pwd)"
 HOOK_PATH="$ROOT_DIR/hooks/freeflow-runtime-context.mjs"
-HOOKS_JSON="$ROOT_DIR/hooks/hooks.json"
+CLAUDE_HOOKS_JSON="$ROOT_DIR/hooks/claude/hooks.json"
+CODEX_HOOKS_JSON="$ROOT_DIR/hooks/codex/hooks.json"
+GEMINI_HOOKS_JSON="$ROOT_DIR/hooks/hooks.json"
+CURSOR_HOOKS_JSON="$ROOT_DIR/hooks/cursor/hooks.json"
+COPILOT_HOOKS_JSON="$ROOT_DIR/com.github.copilot/hooks/hooks.json"
 CORE_PROMPT="$ROOT_DIR/runtime/prompts/core.md"
 INTERACTION_PROMPT="$ROOT_DIR/runtime/prompts/interaction-contract.md"
 
@@ -29,7 +33,9 @@ assert_not_contains() {
 }
 
 [[ -f "$HOOK_PATH" ]] || fail "missing hook script"
-[[ -f "$HOOKS_JSON" ]] || fail "missing hooks manifest"
+for hooks_manifest in "$CLAUDE_HOOKS_JSON" "$CODEX_HOOKS_JSON" "$GEMINI_HOOKS_JSON" "$CURSOR_HOOKS_JSON" "$COPILOT_HOOKS_JSON"; do
+  [[ -f "$hooks_manifest" ]] || fail "missing hooks manifest: $hooks_manifest"
+done
 [[ -f "$CORE_PROMPT" ]] || fail "missing core prompt"
 [[ -f "$INTERACTION_PROMPT" ]] || fail "missing interaction contract prompt"
 [[ ! -f "$ROOT_DIR/runtime/prompts/skills.md" ]] || fail "retired skills prompt remains"
@@ -40,7 +46,29 @@ const hooks = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).hooks || {};
 if (!Array.isArray(hooks.SessionStart) || hooks.SessionStart.length !== 1) process.exit(1);
 if (hooks.SessionStart[0]?.matcher !== "startup|resume|clear|compact") process.exit(1);
 if (hooks.UserPromptSubmit || hooks.SessionEnd) process.exit(1);
-' "$HOOKS_JSON" || fail "hooks.json does not expose only SessionStart"
+' "$CODEX_HOOKS_JSON" || fail "Codex hooks manifest does not expose only SessionStart"
+node -e '
+const fs = require("fs");
+const hooks = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).hooks || {};
+if (!Array.isArray(hooks.SessionStart) || hooks.SessionStart.length !== 1) process.exit(1);
+if (hooks.SessionStart[0]?.matcher !== "startup|resume|clear|compact") process.exit(1);
+' "$CLAUDE_HOOKS_JSON" || fail "Claude hooks manifest does not preserve lifecycle starts"
+node -e '
+const fs = require("fs");
+const hooks = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).hooks || {};
+if (!Array.isArray(hooks.SessionStart) || hooks.SessionStart.length !== 1) process.exit(1);
+if (Object.prototype.hasOwnProperty.call(hooks.SessionStart[0], "matcher")) process.exit(1);
+' "$GEMINI_HOOKS_JSON" || fail "Gemini hooks manifest does not expose SessionStart"
+node -e '
+const fs = require("fs");
+const hooks = JSON.parse(fs.readFileSync(process.argv[1], "utf8")).hooks || {};
+if (!Array.isArray(hooks.sessionStart) || hooks.sessionStart.length !== 1) process.exit(1);
+' "$CURSOR_HOOKS_JSON" || fail "Cursor hooks manifest does not expose sessionStart"
+node -e '
+const fs = require("fs");
+const config = JSON.parse(fs.readFileSync(process.argv[1], "utf8"));
+if (config.version !== 1 || !Array.isArray(config.hooks?.SessionStart) || config.hooks.SessionStart.length !== 1) process.exit(1);
+' "$COPILOT_HOOKS_JSON" || fail "Copilot hooks manifest does not expose versioned SessionStart"
 
 tmp_dir="$(mktemp -d)"
 trap 'rm -rf "$tmp_dir"' EXIT
@@ -81,6 +109,9 @@ assert_not_contains "$codex_output" "session-modes" "configured core context"
 whitespace_root="$(mktemp -d)"
 mkdir -p "$whitespace_root/hooks" "$whitespace_root/runtime/prompts" "$whitespace_root/repo/.freeflow"
 cp "$HOOK_PATH" "$whitespace_root/hooks/freeflow-runtime-context.mjs"
+mkdir -p "$whitespace_root/hooks/adapters" "$whitespace_root/hooks/shared"
+cp "$ROOT_DIR/hooks/adapters/codex-session-start.mjs" "$whitespace_root/hooks/adapters/codex-session-start.mjs"
+cp "$ROOT_DIR/hooks/shared/runtime-context.mjs" "$whitespace_root/hooks/shared/runtime-context.mjs"
 cp -R "$ROOT_DIR/runtime/prompts/." "$whitespace_root/runtime/prompts/"
 printf ' \n\t\n' >"$whitespace_root/runtime/prompts/core.md"
 printf '{}\n' >"$whitespace_root/repo/.freeflow/config.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hassangameryt/freeflow",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "description": "Feedback-based control system for coding agents.",
   "publishConfig": {
     "access": "public"
@@ -22,8 +22,9 @@
     "build:pi-extension": "tsc -p pi-extension/tsconfig.json && npm run format:pi-extension-dist",
     "build": "npm run build:pi-extension",
     "typecheck": "tsc -p pi-extension/tsconfig.json --noEmit",
-    "check": "npm run typecheck && npm run check:source && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run format:check && npm run check:release-version && npm run check:commands && npm run check:activation && npm run check:runtime && npm run check:package",
+    "check": "npm run typecheck && npm run check:source && npm run check:host-manifests && npm run check:changelog && npm run check:release-workflow && npm run check:docs && npm run format:check && npm run check:release-version && npm run check:commands && npm run check:activation && npm run check:runtime && npm run check:package",
     "check:source": "node scripts/validation/check-source-files.mjs",
+    "check:host-manifests": "node scripts/validation/check-host-manifests.mjs",
     "check:changelog": "node scripts/validation/check-changelog.mjs --structure",
     "check:release-workflow": "node scripts/validation/check-release-workflow.mjs",
     "check:docs": "node scripts/validation/check-docs.mjs",
@@ -34,6 +35,7 @@
     "check:package": "node scripts/validation/check-package.mjs",
     "check:release-metadata": "scripts/validation/validate-release-metadata.sh --mode prepublish",
     "test:pi-extension": "npm run build && node --test $(find pi-extension/tests -name '*.test.js' | sort)",
+    "test:host-manifests": "node --test scripts/validation/check-host-manifests.test.mjs hooks/tests/check-host-adapters.test.mjs",
     "test:skill-author": "node --test $(find .skill-eval/write-skill/tests -name '*.test.mjs' | sort)",
     "test:skill-eval": "node --test $(find .skill-eval/evaluate-skill/tests -name '*.test.mjs' | sort)",
     "test:track-work": "node --test .skill-eval/track-work/tests/*.test.mjs",
@@ -59,7 +61,15 @@
     "review",
     "codex",
     "claude",
-    "pi"
+    "pi",
+    "agent-plugins",
+    "gemini",
+    "cursor",
+    "copilot",
+    "vscode",
+    "kiro",
+    "opencode",
+    "hermes"
   ],
   "pi": {
     "skills": [],
@@ -69,9 +79,13 @@
     "image": "https://raw.githubusercontent.com/hassan-mohiddin/freeflow/main/assets/freeflow-plugin-icon-transparent.png"
   },
   "files": [
+    "plugin.json",
+    "gemini-extension.json",
     ".agents/**",
     ".claude-plugin/**",
     ".codex-plugin/**",
+    ".cursor-plugin/**",
+    "com.github.copilot/**",
     "LICENSE",
     "README.md",
     "assets/**",

package/plugin.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "freeflow",
+  "version": "0.7.1",
+  "description": "Feedback-based control system for coding agents.",
+  "author": {
+    "name": "Hassan Mohiddin"
+  },
+  "homepage": "https://github.com/hassan-mohiddin/freeflow",
+  "repository": "https://github.com/hassan-mohiddin/freeflow",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "skills",
+    "agents",
+    "feedback-loop",
+    "task-memory",
+    "planning",
+    "verification",
+    "review",
+    "agent-plugins",
+    "gemini",
+    "copilot",
+    "vscode",
+    "cursor",
+    "kiro",
+    "opencode",
+    "hermes"
+  ],
+  "extensions": {
+    "com.github.copilot": {}
+  }
+}