Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

fix(hooks): Codex hooks.json schema + PreToolUse verdict compat (#2857)

rUvfabcc9261a2a
diff --git a/.claude-plugin/hooks/hooks.json b/.claude-plugin/hooks/hooks.json
index 437812d489..86e57d404a 100644
--- a/.claude-plugin/hooks/hooks.json
+++ b/.claude-plugin/hooks/hooks.json
@@ -1,9 +1,7 @@
{
- "_note": "#1921 β€” hook commands invoke scripts/ruflo-hook.sh (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure (e.g. arborist `Invalid Version` on npm 10.8.x) never surfaces an error in Claude Code or blocks a turn. The trailing `|| true` guards the case where $CLAUDE_PLUGIN_ROOT is unset (older Claude Code) β€” the hook then no-ops silently. DO NOT revert to a bare `npx <pkg>@alpha hooks …` per fire.",
+ "description": "Hook commands invoke scripts/ruflo-hook.sh (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure never surfaces an error in Claude Code or blocks a turn. The trailing `|| true` guards the case where $CLAUDE_PLUGIN_ROOT is unset (older Claude Code) β€” the hook then no-ops silently. This manifest is intentionally POSIX-only (Mac/Linux): it uses /bin/bash, POSIX pipelines (jq, xargs, tr), and .sh scripts, and is known-broken on native Windows. It is a separately-published legacy \"claude-flow\" plugin package (not in the ruflo marketplace list) with its own jq/xargs-based hook set and its own scripts/ruflo-hook.cjs that this file never references β€” still needs its own Windows-compatible, Node-based rewrite.",
"_platform": "posix",
- "_platform_note": "#2132 β€” This hooks.json uses /bin/bash, POSIX pipelines (jq, xargs, tr), and .sh scripts. It is intentionally POSIX-only (Mac/Linux) today and known-broken on native Windows (#2721 shape). The previous claim here that `ruflo init` overrides these entries with node-based equivalents on Windows was never actually implemented and is incorrect β€” Claude Code merges plugin-declared hooks additively with any init-generated settings.json, it does not replace them. This package (separate from plugins/ruflo-core, which got the #2721 fix) still needs its own Windows-compatible rewrite; see _legacy_unaudited_shim below.",
"_legacy_unaudited_shim": true,
- "_legacy_unaudited_shim_note": "#2721 fixed plugins/ruflo-core and plugins/ruflo-cost-tracker (marketplace-listed in .claude-plugin/marketplace.json) by rewiring hooks.json to a `node -e` bootstrap around scripts/ruflo-hook.cjs. This older, separately-published \"claude-flow\" plugin package (not in the ruflo marketplace list) has its own, larger jq/xargs-based hook set and its own scripts/ruflo-hook.cjs that hooks.json never references β€” same underlying bug shape, NOT fixed as part of #2721. Needs its own audited pass before this flag can be removed.",
"hooks": {
"PreToolUse": [
{
diff --git a/plugins/ruflo-core/.claude-plugin/plugin.json b/plugins/ruflo-core/.claude-plugin/plugin.json
index 561451c6cb..7030edac4e 100644
--- a/plugins/ruflo-core/.claude-plugin/plugin.json
+++ b/plugins/ruflo-core/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-core",
"description": "Foundation plugin β€” registers the ruflo MCP server (300+ tools across memory/agentdb/embeddings/hooks/aidefence/neural/autopilot/browser/agent/swarm), provides 4 generalist agents (coder/researcher/reviewer/witness-curator), 5 skills (discover-plugins/init-project/ruflo-doctor/ruflo-status/witness), and a curated plugin-discovery catalog",
- "version": "0.2.5",
+ "version": "0.2.6",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-core/docs/adrs/0001-core-contract.md b/plugins/ruflo-core/docs/adrs/0001-core-contract.md
index 52c31695f1..c68de2d7e6 100644
--- a/plugins/ruflo-core/docs/adrs/0001-core-contract.md
+++ b/plugins/ruflo-core/docs/adrs/0001-core-contract.md
@@ -13,9 +13,9 @@ tags: [plugin, core, mcp, foundation, smoke-test]
`ruflo-core` is the **foundation plugin**. Every other plugin (`ruflo-ruvector`, `ruflo-agentdb`, `ruflo-browser`, `ruflo-intelligence`, `ruflo-adr`, `ruflo-aidefence`, `ruflo-autopilot`, plus 25 others) depends on the MCP server it registers via `.mcp.json` and the orchestration patterns it documents.
-The current plugin contract (v0.2.5):
+The current plugin contract (v0.2.6):
-- `.claude-plugin/plugin.json` β€” `version: "0.2.5"`, foundation and discovery metadata
+- `.claude-plugin/plugin.json` β€” `version: "0.2.6"`, foundation and discovery metadata
- `.mcp.json` β€” registers `ruflo` MCP server via `npx -y @claude-flow/cli@latest`
- `agents/` β€” 4 generalists (`coder`, `researcher`, `reviewer`, `witness-curator`)
- `skills/` β€” 5 native skills (`init-project`, `ruflo-doctor`, `ruflo-status`, `discover-plugins`, `witness`)
@@ -56,7 +56,7 @@ Append:
11 checks:
-1. plugin.json declares `0.2.5` with the foundation keywords.
+1. plugin.json declares `0.2.6` with the foundation keywords.
2. `.mcp.json` exists and registers a `ruflo` MCP server.
3. All 4 agents are present with valid frontmatter.
4. All 5 skills are present with valid frontmatter.
@@ -113,4 +113,4 @@ bash plugins/ruflo-core/scripts/smoke.sh
## Implementation status
-Plugin source version v0.2.5 is listed by path in `.claude-plugin/marketplace.json`, so the marketplace artifact includes the five native skills and host-aware hook shim. Contract elements implemented: `.mcp.json` registers the `ruflo` server via `npx -y @claude-flow/cli@latest`; plugin-catalog discovery and Codex-native status skills are present; four generalist agents ship; command/skill parity and the remaining inventory are enforced by `scripts/smoke.sh`.
+Plugin source version v0.2.6 is listed by path in `.claude-plugin/marketplace.json`, so the marketplace artifact includes the five native skills and host-aware hook shim. Contract elements implemented: `.mcp.json` registers the `ruflo` server via `npx -y @claude-flow/cli@latest`; plugin-catalog discovery and Codex-native status skills are present; four generalist agents ship; command/skill parity and the remaining inventory are enforced by `scripts/smoke.sh`.
diff --git a/plugins/ruflo-core/hooks/hooks.json b/plugins/ruflo-core/hooks/hooks.json
index 3f922b9cfd..3193eb687a 100644
--- a/plugins/ruflo-core/hooks/hooks.json
+++ b/plugins/ruflo-core/hooks/hooks.json
@@ -1,6 +1,5 @@
{
- "_note": "#1921/#2613/#2721/#2816 β€” hook commands invoke scripts/ruflo-hook.cjs (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure (e.g. arborist `Invalid Version` on npm 10.8.x) never surfaces an error or blocks a turn. PreToolUse commands emit Cursor's valid `{\"permission\":\"allow\"}` verdict except when Codex's plugin-only PLUGIN_ROOT/PLUGIN_DATA variables are present; Codex unconditional allow is exit 0 with empty stdout. Telemetry runs in both paths. DO NOT revert to a bare `npx <pkg>@alpha hooks …` per fire.",
- "_platform_note": "#2721 β€” every command below is a `node -e` bootstrap: it resolves this plugin's scripts/ruflo-hook.cjs from process.env.CLAUDE_PLUGIN_ROOT INSIDE Node (no shell `${VAR}`/`%VAR%` expansion, so the exact same command string runs unchanged on Windows, macOS, and Linux), then requires it with process.argv pre-seeded for the target subcommand. No bash, sh, cmd.exe, jq, or .sh scripts are involved.",
+ "description": "Hook commands invoke scripts/ruflo-hook.cjs (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure never surfaces an error or blocks a turn. PreToolUse commands emit Cursor's valid `{\"permission\":\"allow\"}` verdict except when a Codex plugin host is detected; Codex unconditional allow is exit 0 with empty stdout (Codex's stricter schema rejects the Cursor-shaped object). Telemetry runs in both paths. Every command below is a `node -e` bootstrap that resolves this plugin's scripts/ruflo-hook.cjs from process.env.CLAUDE_PLUGIN_ROOT inside Node (no shell `${VAR}`/`%VAR%` expansion), so the exact same command string runs unchanged on Windows, macOS, and Linux β€” no bash, sh, cmd.exe, jq, or .sh scripts are involved.",
"hooks": {
"PreToolUse": [
{
diff --git a/plugins/ruflo-core/scripts/ruflo-hook.cjs b/plugins/ruflo-core/scripts/ruflo-hook.cjs
index f91db2fb67..c659ecb9e8 100644
--- a/plugins/ruflo-core/scripts/ruflo-hook.cjs
+++ b/plugins/ruflo-core/scripts/ruflo-hook.cjs
@@ -13,8 +13,11 @@
* - modify-bash / modify-file (PreToolUse) β€” best-effort CLI call, then
* emit `{"permission":"allow"}` for Cursor/Claude compatibility. Codex
* plugin hooks are detected by their Codex-specific PLUGIN_ROOT /
- * PLUGIN_DATA variables and intentionally receive empty stdout: a bare
- * Cursor permission object is not valid Codex hook JSON (#2816).
+ * PLUGIN_DATA variables, falling back to the `turn_id` field Codex
+ * always includes in the hook event JSON, and intentionally receive
+ * empty stdout: a bare Cursor permission object is not valid Codex
+ * hook JSON and is rejected with "hook returned invalid pre-tool-use
+ * JSON output" (#2816, #2856).
* - post-command / post-edit (PostToolUse) β€” parse the hook event JSON
* from stdin (no jq), extract the same fields the bash version pulled
* with jq, and forward them as CLI flags.
@@ -205,9 +208,21 @@ function claimSideEffectEvent(family, stdinData, event) {
* Cursor and Claude Code use CLAUDE_PLUGIN_ROOT without these Codex-specific
* variables. Keep this positive Codex check narrow so existing Cursor
* installations retain their permission response.
+ *
+ * Fallback: Codex's PreToolUse input JSON always carries a `turn_id` string
+ * field (verified against codex-rs' pre-tool-use.command.input schema β€”
+ * it is Codex's own documented extension, not present in Claude Code's or
+ * Cursor's hook payloads). This catches any install/config path where the
+ * PLUGIN_ROOT/PLUGIN_DATA env vars aren't injected, so a stray Cursor-shaped
+ * `{"permission":"allow"}` object never reaches Codex's stricter parser
+ * (#2856): Codex's output_parser rejects unknown top-level keys outright
+ * and reports "hook returned invalid pre-tool-use JSON output" for any
+ * JSON-shaped stdout it can't fit into its schema, whereas empty stdout is
+ * treated as no-opinion/implicit-allow with no error.
*/
-function isCodexPluginHost() {
- return Boolean(process.env.PLUGIN_ROOT || process.env.PLUGIN_DATA);
+function isCodexPluginHost(event) {
+ if (process.env.PLUGIN_ROOT || process.env.PLUGIN_DATA) return true;
+ return typeof event?.turn_id === 'string' && event.turn_id.length > 0;
}
/**
@@ -285,7 +300,7 @@ function main() {
// Codex unconditional allow is exit 0 with empty stdout (#2816).
if (subcommand === 'modify-bash' || subcommand === 'modify-file') {
invokeCli(subcommand, [], stdinData);
- if (!isCodexPluginHost()) {
+ if (!isCodexPluginHost(event)) {
process.stdout.write('{"permission":"allow"}');
}
done();
diff --git a/plugins/ruflo-core/scripts/smoke.sh b/plugins/ruflo-core/scripts/smoke.sh
index df28a76775..8bfa5a6aa6 100755
--- a/plugins/ruflo-core/scripts/smoke.sh
+++ b/plugins/ruflo-core/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural smoke test for ruflo-core v0.2.5 (ADR-0001).
+# Structural smoke test for ruflo-core v0.2.6 (ADR-0001).
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
@@ -8,10 +8,10 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.2.5 with new keywords"
+step "1. plugin.json declares 0.2.6 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.2.5" ]]; then
- bad "expected 0.2.5, got '$v'"
+if [[ "$v" != "0.2.6" ]]; then
+ bad "expected 0.2.6, got '$v'"
else
miss=""
for k in foundation mcp-server plugin-catalog discovery; do
diff --git a/plugins/ruflo-core/scripts/test-hooks.mjs b/plugins/ruflo-core/scripts/test-hooks.mjs
index dabbf93696..6f09f62903 100644
--- a/plugins/ruflo-core/scripts/test-hooks.mjs
+++ b/plugins/ruflo-core/scripts/test-hooks.mjs
@@ -1,6 +1,6 @@
#!/usr/bin/env node
/**
- * Regression guard for ruvnet/ruflo#1859, #1862, #2721, #2816.
+ * Regression guard for ruvnet/ruflo#1859, #1862, #2721, #2816, #2856.
*
* Drives every hook command from `hooks/hooks.json` β€” PreToolUse,
* PostToolUse, PreCompact, Stop β€” with synthetic Claude-Code-style stdin,
@@ -187,6 +187,24 @@ run('Codex PreToolUse (Edit) still invokes telemetry',
[{ contains: 'hook-telemetry:modify-file' }, { absent: '{"permission":"allow"}' }],
codexEnv);
+// #2856 β€” Codex's PLUGIN_ROOT/PLUGIN_DATA env vars may not be present on
+// every install/config path; the `turn_id` field Codex always includes in
+// the hook event JSON is a documented Codex-only extension and must be
+// enough on its own to suppress the Cursor-shaped permission object.
+const codexTurnIdOnlyEnv = { unsetEnv: ['PLUGIN_ROOT', 'PLUGIN_DATA'] };
+
+run('Codex PreToolUse (Bash) detected via turn_id alone (no PLUGIN_ROOT/PLUGIN_DATA) exits 0 with empty stdout',
+ cmdModifyBash,
+ '{"hook_event_name":"PreToolUse","turn_id":"turn_2856","model":"gpt-5.6-sol","tool_name":"Bash","tool_input":{"command":"echo hi"}}',
+ [{ stdoutEquals: '' }],
+ { ...codexTurnIdOnlyEnv, debug: false });
+
+run('Cursor PreToolUse (Bash) without turn_id still emits permission-allow JSON',
+ cmdModifyBash,
+ '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"}}',
+ [{ contains: '{"permission":"allow"}' }],
+ codexTurnIdOnlyEnv);
+
// --- PostToolUse: post-edit ---
run('Edit hook records file_path (regression #1859: was "true")',
cmdPostEdit,
diff --git a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
index 33cd0bd728..68b4b471c5 100644
--- a/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
+++ b/plugins/ruflo-cost-tracker/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-cost-tracker",
"description": "Token usage tracking, model cost attribution per agent, budget alerts, and optimization recommendations β€” uses memory_* (namespace-routed) for cost-tracking and cost-patterns; pairs with federation budget circuit breaker (ADR-097)",
- "version": "0.26.2",
+ "version": "0.26.3",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-cost-tracker/hooks/hooks.json b/plugins/ruflo-cost-tracker/hooks/hooks.json
index 4e8daf9821..203b2fa4ba 100644
--- a/plugins/ruflo-cost-tracker/hooks/hooks.json
+++ b/plugins/ruflo-cost-tracker/hooks/hooks.json
@@ -1,6 +1,5 @@
{
- "_note": "Stop hook auto-runs cost-track at session end so the cost-tracking namespace stays populated without users remembering to run `/cost-track` manually. TRACK_QUIET=1 suppresses the markdown summary (avoid spamming on every Stop). A track failure NEVER blocks session end β€” analytics data is best-effort, not load-bearing (see scripts/ruflo-hook.cjs).",
- "_platform_note": "#2721 β€” the command below is a `node -e` bootstrap: it resolves scripts/ruflo-hook.cjs from process.env.CLAUDE_PLUGIN_ROOT INSIDE Node (no shell `${VAR}`/`%VAR%` expansion), so the exact same command string runs unchanged on Windows, macOS, and Linux. No bash or /dev/null redirection involved.",
+ "description": "Stop hook auto-runs cost-track at session end so the cost-tracking namespace stays populated without users remembering to run `/cost-track` manually. TRACK_QUIET=1 suppresses the markdown summary. A track failure never blocks session end β€” analytics data is best-effort, not load-bearing (see scripts/ruflo-hook.cjs). The command is a `node -e` bootstrap: it resolves scripts/ruflo-hook.cjs from process.env.CLAUDE_PLUGIN_ROOT inside Node (no shell `${VAR}`/`%VAR%` expansion), so the exact same command string runs unchanged on Windows, macOS, and Linux β€” no bash or /dev/null redirection involved.",
"hooks": {
"Stop": [
{
diff --git a/plugins/ruflo-cost-tracker/scripts/smoke.sh b/plugins/ruflo-cost-tracker/scripts/smoke.sh
index a901f17b2f..9dd6724c6d 100755
--- a/plugins/ruflo-cost-tracker/scripts/smoke.sh
+++ b/plugins/ruflo-cost-tracker/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural smoke test for ruflo-cost-tracker v0.26.2.
+# Structural smoke test for ruflo-cost-tracker v0.26.3.
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
@@ -8,10 +8,10 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.26.2 with new keywords"
+step "1. plugin.json declares 0.26.3 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.26.2" ]]; then
- bad "expected 0.26.2, got '$v'"
+if [[ "$v" != "0.26.3" ]]; then
+ bad "expected 0.26.3, got '$v'"
else
miss=""
for k in namespace-routing mcp agentic-flow agent-booster tier1-routing model-routing benchmarking verified telemetry budget projection forecast counterfactual drift-detection trend-alert anomaly-detection outlier-detection health-check composite-gate auto-track stop-hook snapshot-diff pr-regression git-context traceability drill-down per-message; do
diff --git a/scripts/audit-plugin-hooks-cross-platform.mjs b/scripts/audit-plugin-hooks-cross-platform.mjs
index 203e276508..b56e6d1315 100644
--- a/scripts/audit-plugin-hooks-cross-platform.mjs
+++ b/scripts/audit-plugin-hooks-cross-platform.mjs
@@ -42,6 +42,18 @@
* False-positive avoidance: only the `command` field of `hooks[].hooks[]`
* entries is scanned. Comments, descriptions, and the top-level `_note`
* field are ignored.
+ *
+ * ## Codex strict top-level-key guard (ruvnet/ruflo#2855)
+ *
+ * Codex's plugin hook-manifest loader accepts only `description` and
+ * `hooks` at the top level and hard-fails ("unknown field `_note`,
+ * expected `description` or `hooks`") on anything else β€” it never loads
+ * the plugin at all, so every hook in it silently stops firing. Every
+ * marketplace-listed, Codex-facing `hooks.json` (see CODEX_FACING_PATHS
+ * below) is checked for unknown top-level keys. Legacy, non-marketplace
+ * manifests (`.claude-plugin/hooks/hooks.json`, `plugin/hooks/hooks.json`)
+ * are intentionally out of scope β€” they are not fetched via the ruflo
+ * marketplace path Codex installs from.
*/
import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
@@ -51,6 +63,14 @@ import { dirname, join, relative, resolve, basename } from 'node:path';
const __dirname = dirname(fileURLToPath(import.meta.url));
const REPO_ROOT = resolve(__dirname, '..');
+// Marketplace-listed hooks.json files Codex actually fetches and parses
+// with its strict `description`+`hooks`-only top-level schema (#2855).
+const CODEX_FACING_PATHS = new Set([
+ 'plugins/ruflo-core/hooks/hooks.json',
+ 'plugins/ruflo-cost-tracker/hooks/hooks.json',
+]);
+const CODEX_ALLOWED_TOP_LEVEL_KEYS = new Set(['description', 'hooks']);
+
// Directories to skip when walking
const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'coverage']);
@@ -110,6 +130,39 @@ for (const file of walkForHooksJson(REPO_ROOT)) {
continue;
}
+ // --- Codex strict top-level-key guard (#2855) ---
+ const relForCodexCheck = relative(REPO_ROOT, file);
+ if (CODEX_FACING_PATHS.has(relForCodexCheck)) {
+ const unknownKeys = Object.keys(json).filter((key) => !CODEX_ALLOWED_TOP_LEVEL_KEYS.has(key));
+ if (unknownKeys.length > 0) {
+ violations.push({
+ file: relForCodexCheck,
+ line: 1,
+ label: 'Codex-incompatible top-level hook-manifest key(s)',
+ cmd: unknownKeys.join(', '),
+ hint: 'Codex only accepts `description` and `hooks` at the top level and refuses to load the whole plugin otherwise (#2855) β€” fold any maintenance notes into `description` or move them to docs/comments elsewhere.',
+ });
+ }
+ if (Object.hasOwn(json, 'description') && typeof json.description !== 'string') {
+ violations.push({
+ file: relForCodexCheck,
+ line: 1,
+ label: 'Codex hook-manifest `description` must be a string',
+ cmd: `description is ${typeof json.description}`,
+ hint: 'Use a user-facing string description or omit the optional field.',
+ });
+ }
+ if (typeof json.hooks !== 'object' || json.hooks === null || Array.isArray(json.hooks)) {
+ violations.push({
+ file: relForCodexCheck,
+ line: 1,
+ label: 'Codex hook-manifest `hooks` must be a non-null object',
+ cmd: `hooks is ${Array.isArray(json.hooks) ? 'an array' : typeof json.hooks}`,
+ hint: 'hooks.json must declare `"hooks": { "PreToolUse": [...], ... }`.',
+ });
+ }
+ }
+
// --- POSIX-only exemption check (#2132, hardened #2721) ---
if (json._platform === 'posix') {
const relFile = relative(REPO_ROOT, file);