π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(hooks): Codex hooks.json schema + PreToolUse verdict compat (#2857)
rUvfabcc9261a2a
diff --git a/.claude-plugin/hooks/hooks.json b/.claude-plugin/hooks/hooks.jsonindex 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.jsonindex 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.mdindex 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.jsonindex 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.cjsindex 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.shindex 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 -uROOT="$(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'"elsemiss=""for k in foundation mcp-server plugin-catalog discovery; dodiff --git a/plugins/ruflo-core/scripts/test-hooks.mjs b/plugins/ruflo-core/scripts/test-hooks.mjsindex 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.jsonindex 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.jsonindex 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.shindex 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 -uROOT="$(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'"elsemiss=""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; dodiff --git a/scripts/audit-plugin-hooks-cross-platform.mjs b/scripts/audit-plugin-hooks-cross-platform.mjsindex 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 walkingconst 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);