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

feat(ruflo-mods): capabilityProbe option records engine version and events fired (default off), ADR-451 item 5; 0.3.6

ruv32b6c3300823
diff --git a/plugins/ruflo-mods/.claude-plugin/plugin.json b/plugins/ruflo-mods/.claude-plugin/plugin.json
index 89ba5ed5e0..cbb71f3b4f 100644
--- a/plugins/ruflo-mods/.claude-plugin/plugin.json
+++ b/plugins/ruflo-mods/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-mods",
"description": "ruflo as a Claude Code mod (function hooks, ADR-404): in-process prompt routing, edit learning signals, tighten-only tool checks from ruflo policy, the cost-tracker budget ladder, a mod trust gate for newly installed mods, and the $.ruflo noun other mods compose their status with. Opt-in and removable: the classic hook-handler hooks stay the default and take every event back whenever the mod is not loaded.",
- "version": "0.3.5",
+ "version": "0.3.6",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -75,6 +75,13 @@
"required": false,
"default": false
},
+ "capabilityProbe": {
+ "type": "boolean",
+ "title": "Capability probe",
+ "description": "Record the engine version and which of this mod's events actually fired, and show it as one line in /ruflo-mods (probe: engine ... · events fired n/m · never fired: ...). Observability only: never denies, rewrites or delays anything. Off by default.",
+ "required": false,
+ "default": false
+ },
"modTrust": {
"type": "string",
"title": "Mod trust gate",
diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.md
index 0859db11d9..004b7eb611 100644
--- a/plugins/ruflo-mods/README.md
+++ b/plugins/ruflo-mods/README.md
@@ -84,6 +84,7 @@ Claude Code reads a plugin's options from `pluginConfigs["ruflo-mods@ruflo"].opt
| `costBudgetUsd` | `0` (off) | Session budget for the ladder |
| `costHardStop` | `false` | Refuse new subagents at 100% of budget |
| `deliveryScreen` | `false` | In-process screen (ADR-451): drops peer or relay deliveries that carry injection phrasing, refuses outgoing messages that carry a secret shape. Never screens your own Remote Control prompts; names the rule, never the text |
+| `capabilityProbe` | `false` | Observability only (ADR-451 item 5): the `/ruflo-mods` report gains `probe: engine <version> · events fired n/m · never fired: ...`, and the heartbeat file lists the engine version and registered events. Reads no event payload; never denies, rewrites or delays; the version is shown as "not exposed" when the build does not answer `$.session.version()` |
| `modTrust` | `observe` | `observe` / `refuse-risky` / `off`: the mod trust gate |
| `modTrustAllow` | `` | Comma-separated plugin ids (`name@marketplace`, e.g. `ruflo-swarm@ruflo,ruflo-console@ruflo`) the gate never refuses |
diff --git a/plugins/ruflo-mods/hooks/options.ts b/plugins/ruflo-mods/hooks/options.ts
index 9fdd72e3ed..9402a41c14 100644
--- a/plugins/ruflo-mods/hooks/options.ts
+++ b/plugins/ruflo-mods/hooks/options.ts
@@ -15,6 +15,7 @@ export type ModOptions = {
readonly agentTrim: boolean
readonly agentTrimKeep: ReadonlySet<string>
readonly deliveryScreen: boolean
+ readonly capabilityProbe: boolean
readonly modTrust: TrustPolicy
readonly modTrustAllow: ReadonlySet<string>
}
@@ -43,6 +44,7 @@ export function readOptions(options: PluginOptions | undefined): ModOptions {
agentTrim: bool(o.agentTrim, false),
agentTrimKeep: keepNames(o.agentTrimKeep),
deliveryScreen: bool(o.deliveryScreen, false),
+ capabilityProbe: bool(o.capabilityProbe, false),
modTrust: TRUST.includes(o.modTrust as TrustPolicy) ? (o.modTrust as TrustPolicy) : 'observe',
modTrustAllow: names(o.modTrustAllow),
}
diff --git a/plugins/ruflo-mods/hooks/probe/index.ts b/plugins/ruflo-mods/hooks/probe/index.ts
new file mode 100644
index 0000000000..f0f605caec
--- /dev/null
+++ b/plugins/ruflo-mods/hooks/probe/index.ts
@@ -0,0 +1,79 @@
+import type { On } from 'claude-code'
+
+import type { ModOptions } from '../options'
+import type { ModState } from '../state'
+
+/**
+ * Capability probe (ADR-451 item 5): observability only. Off unless
+ * `capabilityProbe` is on. It counts which of the events this module registered
+ * fired, and keeps the engine version `$.session.version()`
+ * reports, so `/ruflo-mods` can say "registered but never fired" when a build
+ * renames or withholds an event. It reads no event payload, answers nothing,
+ * writes nothing of its own and never changes, delays or denies a hook: each
+ * event is handed on unchanged.
+ */
+export type ProbeState = {
+ enabled: boolean
+ /** Engine version as `$.session.version()` gave it; undefined when the build does not expose it. */
+ version?: string
+ /** Event names the module registered (pattern strings, ours, never payload). */
+ registered: Set<string>
+ fired: Map<string, number>
+}
+
+export const probeState = (): ProbeState => ({ enabled: false, registered: new Set(), fired: new Map() })
+
+const MAX_LINE = 240
+
+/**
+ * The events this module registers, by name. The engine reads `on` calls
+ * statically (it refuses a wrapped or aliased `on`), so the list is kept here
+ * and a test fails when it drifts from the `on('<event>', ...)` calls in hooks/.
+ */
+const ALWAYS = ['agent.spawn', 'command.run', 'engine.create', 'plugin.register', 'prompt.submit', 'session.end', 'session.measure', 'session.start', 'tool.call', 'tool.check', 'turn.complete'] as const
+
+export function registeredEvents(opts: Pick<ModOptions, 'toolHints' | 'agentTrim' | 'deliveryScreen'>): string[] {
+ const names: string[] = [...ALWAYS]
+ if (opts.toolHints) names.push('tool.describe')
+ if (opts.agentTrim) names.push('agent.offer')
+ if (opts.deliveryScreen) names.push('session.receive', 'session.send')
+ return names.sort()
+}
+
+/**
+ * One pass-through hook on every event: it counts the events the module
+ * registered and hands the event on unchanged, answering nothing. Any failure
+ * of its own passes the event on.
+ */
+export function registerProbe(on: On, state: ModState, opts: ModOptions) {
+ state.probe.enabled = true
+ for (const name of registeredEvents(opts)) state.probe.registered.add(name)
+ on('*', ($, e, next) => {
+ try {
+ const name = (next as { event?: unknown }).event
+ if (typeof name === 'string' && state.probe.registered.has(name)) state.probe.fired.set(name, (state.probe.fired.get(name) ?? 0) + 1)
+ } catch {
+ // counting must not change what any hook does
+ }
+ return next(e)
+ }).catch(($, e, next) => next(e))
+}
+
+/** The version string kept from `$.session.version()`: printable, short; anything else is "not exposed". */
+export function versionText(value: unknown): string | undefined {
+ const { version, base } = (value ?? {}) as { version?: unknown; base?: unknown }
+ const text = typeof base === 'string' && base ? base : version
+ return typeof text === 'string' && /^[A-Za-z0-9._+-]{1,40}$/.test(text) ? text : undefined
+}
+
+/** The bounded status line `/ruflo-mods` shows. */
+export function probeLine(probe: ProbeState): string {
+ if (!probe.enabled) return 'off (set the capabilityProbe option)'
+ const names = [...probe.registered].sort()
+ const fired = names.filter(n => (probe.fired.get(n) ?? 0) > 0).length
+ const never = names.filter(n => !probe.fired.get(n))
+ const engine = probe.version ? `engine ${probe.version}` : 'engine version not exposed'
+ const tail = never.length ? ` · never fired: ${never.join(', ')}` : ''
+ const line = `probe: ${engine} · events fired ${fired}/${names.length}${tail}`
+ return line.length > MAX_LINE ? `${line.slice(0, MAX_LINE - 1)}…` : line
+}
diff --git a/plugins/ruflo-mods/hooks/register.ts b/plugins/ruflo-mods/hooks/register.ts
index 152b1316b7..98052e6421 100644
--- a/plugins/ruflo-mods/hooks/register.ts
+++ b/plugins/ruflo-mods/hooks/register.ts
@@ -9,6 +9,7 @@ import { createGuidance } from './guidance'
import { registerLearn } from './learn'
import { registerNoun } from './noun'
import { readOptions } from './options'
+import { registerProbe } from './probe'
import { registerRoute } from './route'
import { registerSession } from './session'
import { createState } from './state'
@@ -32,6 +33,7 @@ export const register: Register = (on, options) => {
const guidance = createGuidance(state, opts)
registerTrust(on, opts.modTrust, opts.modTrustAllow)
+ if (opts.capabilityProbe) registerProbe(on, state, opts)
registerNoun(on, state)
registerSession(on, state, opts, guidance)
registerRoute(on, state, opts, guidance)
diff --git a/plugins/ruflo-mods/hooks/session.ts b/plugins/ruflo-mods/hooks/session.ts
index 313afac51d..e7b4f7d5f9 100644
--- a/plugins/ruflo-mods/hooks/session.ts
+++ b/plugins/ruflo-mods/hooks/session.ts
@@ -1,6 +1,7 @@
import type { EngineInterface, On } from 'claude-code'
import type { GuidanceHooks } from './guidance'
+import { versionText } from './probe'
import { HANDSHAKE_MARKER, ownedEvents } from './ownership'
import type { ModOptions } from './options'
import { redraw, report, under, type ModState } from './state'
@@ -55,13 +56,14 @@ export function registerSession(on: On, state: ModState, options: ModOptions, gu
state.owned = new Set(project ? ownedEvents(settings, await helperHonours($)) : [])
await $.env.set('RUFLO_MODS_OWNS', state.owned.size ? [...state.owned].join(',') : undefined)
state.statusLine = options.statusLine && !hasClassicStatusLine(settings)
+ if (state.probe.enabled) state.probe.version = versionText(await $.session.version().catch(() => undefined))
guidance?.start()
redraw(state)
await $.command
.register({ name: 'ruflo-mods', description: 'Same as /ruflo mods: what this session routed, recorded and tightened' })
.catch(() => undefined)
if (project) {
- const heartbeat = { startedAt: new Date().toISOString(), owned: [...state.owned], statusLine: state.statusLine }
+ const heartbeat = { startedAt: new Date().toISOString(), owned: [...state.owned], statusLine: state.statusLine, ...(state.probe.enabled ? { engine: state.probe.version ?? null, events: [...state.probe.registered].sort() } : {}) }
await $.fs.write(under(state, HEARTBEAT_PATH), `${JSON.stringify(heartbeat, null, 2)}\n`).catch(() => undefined)
}
return next(e)
diff --git a/plugins/ruflo-mods/hooks/state.ts b/plugins/ruflo-mods/hooks/state.ts
index 7c818e1bd3..deb48884cf 100644
--- a/plugins/ruflo-mods/hooks/state.ts
+++ b/plugins/ruflo-mods/hooks/state.ts
@@ -2,6 +2,7 @@ import type { BudgetLevel } from './cost/budget'
import type { EditRecord } from './learn/insights'
import { guidanceState, type GuidanceState } from './guidance/observations'
import type { Ownable } from './ownership'
+import { probeLine, probeState, type ProbeState } from './probe'
import type { RouteResult } from './route/route-task'
/**
@@ -34,6 +35,8 @@ export type ModState = {
agentTrim: { enabled: boolean; hidden: Set<string>; prompt: string; ledger?: Promise<Record<string, number>> }
/** `session.receive`/`session.send` screen (ADR-451): whether it is on, deliveries consumed, sends refused. */
delivery: { enabled: boolean; consumed: number; blocked: number }
+ /** Capability probe (ADR-451 item 5): engine version and which registered events fired. */
+ probe: ProbeState
/** Other mods' status segments, by id (`$.ruflo.segment`). */
segments: Map<string, string>
/**
@@ -59,6 +62,7 @@ export function createState(): ModState {
toolHints: { enabled: false, described: new Set() },
agentTrim: { enabled: false, hidden: new Set(), prompt: '' },
delivery: { enabled: false, consumed: 0, blocked: 0 },
+ probe: probeState(),
segments: new Map(),
draw: () => undefined,
}
@@ -144,6 +148,7 @@ export function report(s: ModState): string {
` tool hints: ${s.toolHints.enabled ? `${s.toolHints.described.size} tool(s) described` : 'off (set the toolHints option)'}`,
` agent trim: ${s.agentTrim.enabled ? `${s.agentTrim.hidden.size} type(s) hidden` : 'off (set the agentTrim option)'}`,
` delivery: ${s.delivery.enabled ? `${s.delivery.consumed} dropped, ${s.delivery.blocked} refused` : 'off (set the deliveryScreen option)'}`,
+ ` probe: ${probeLine(s.probe)}`,
` segments: ${segments.join(', ') || 'none'}`,
` guidance: ${s.guidance.status}; ${s.guidance.saved} unverified observation(s), ${s.guidance.pending.length} pending, ${s.guidance.dropped} dropped`,
]
diff --git a/plugins/ruflo-mods/scripts/smoke.sh b/plugins/ruflo-mods/scripts/smoke.sh
index 2b63b58a14..f166dca766 100755
--- a/plugins/ruflo-mods/scripts/smoke.sh
+++ b/plugins/ruflo-mods/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural + security smoke for ruflo-mods v0.3.5 (ADR-404, ADR-447).
+# Structural + security smoke for ruflo-mods v0.3.6 (ADR-404, ADR-447).
# Static only: CI has no Claude Code, so the hooks module's behaviour is held
# by v3/@claude-flow/cli/__tests__/mods/*.test.ts and, where function hooks are
# on, by `claude plugin test plugins/ruflo-mods`.
@@ -12,9 +12,9 @@ ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
HOOKS="$ROOT/hooks"
-step "1. plugin.json declares ruflo-mods 0.3.5"
+step "1. plugin.json declares ruflo-mods 0.3.6"
grep -q '"name": "ruflo-mods"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.3.5"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.3.6"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
@@ -32,7 +32,7 @@ hits=$(grep -rnE '\$\.(http|process|model|mcp)\.' "$HOOKS" || true)
step "5. only the documented events are hooked"
events=$(grep -rhoE "on\('[a-z.*]+'" "$HOOKS" | sort -u | tr '\n' ' ')
-expected="on('agent.offer' on('agent.spawn' on('command.run' on('engine.create' on('plugin.register' on('prompt.submit' on('session.end' on('session.measure' on('session.receive' on('session.send' on('session.start' on('tool.call' on('tool.check' on('tool.describe' on('turn.complete' "
+expected="on('*' on('agent.offer' on('agent.spawn' on('command.run' on('engine.create' on('plugin.register' on('prompt.submit' on('session.end' on('session.measure' on('session.receive' on('session.send' on('session.start' on('tool.call' on('tool.check' on('tool.describe' on('turn.complete' "
[[ "$events" == "$expected" ]] && ok || bad "got: $events"
step "6. tool.check merges with stricter() (tighten-only)"
@@ -60,5 +60,13 @@ step "11. guidance observations cannot train or promote"
hits=$(grep -rnE '(hooks_post-task|outcomeAccepted|applyPromotions|runCycle|optimize\(|events\.ndjson)' "$HOOKS/guidance" || true)
[[ -z "$hits" ]] && grep -q 'learningEligible: false' "$HOOKS/guidance/observations.ts" && ok || bad "guidance must remain candidate-only"
+step "12. the capability probe is observability only and lists every event hooked"
+missing=""
+for ev in $(grep -rhoE "on\('[a-z.]+'" "$HOOKS" | sed -E "s/on\('(.*)'/\1/" | sort -u); do
+ grep -q "'$ev'" "$HOOKS/probe/index.ts" || missing="$missing $ev"
+done
+[[ -z "$missing" ]] && ! grep -nE "decision|deny|consumed|isDelivered|\\$\.(fs|env|ui)\." "$HOOKS/probe/index.ts" >/dev/null \
+ && ok || bad "probe event list missing:$missing, or the probe answers/writes"
+
printf "\n%d passed, %d failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]]
diff --git a/plugins/ruflo-mods/tests/probe.test.ts b/plugins/ruflo-mods/tests/probe.test.ts
new file mode 100644
index 0000000000..6792038fd7
--- /dev/null
+++ b/plugins/ruflo-mods/tests/probe.test.ts
@@ -0,0 +1,100 @@
+import { describe, expect, test, tier } from 'claude-code/testing'
+
+import { probeLine, probeState, registeredEvents, versionText } from '../hooks/probe'
+import { run } from './fixtures/consumer'
+import { HELPER, ROOT, START, world } from './fixtures/world'
+
+tier('user')
+
+describe('capability probe, pure (ADR-451 item 5)', () => {
+ test('version text: release base wins, anything unprintable is not exposed', () => {
+ expect(versionText({ version: '2.1.287', base: '2.1.287' })).toBe('2.1.287')
+ expect(versionText({ version: '2.1.280-dev.20260920.t1.sha1a2b3c4', base: '2.1.280-dev' })).toBe('2.1.280-dev')
+ expect(versionText({ version: '2.1.287' })).toBe('2.1.287')
+ for (const bad of [undefined, null, 7, {}, { version: 'x\u001b[2Jy' }, { version: 'a'.repeat(41) }, { version: '' }]) expect(versionText(bad)).toBeUndefined()
+ })
+
+ test('the line is bounded however many events never fired', () => {
+ const probe = probeState()
+ probe.enabled = true
+ for (let i = 0; i < 64; i++) probe.registered.add(`never.fired.event.number.${i}`)
+ const line = probeLine(probe)
+ expect(line.length).toBeLessThanOrEqual(240)
+ expect(line).toContain('events fired 0/64')
+ })
+
+ test('the registered-event list grows with the options that register more events (smoke.sh checks it against hooks/)', () => {
+ const off = registeredEvents({ toolHints: false, agentTrim: false, deliveryScreen: false })
+ expect(off).not.toContain('tool.describe')
+ expect(off).toContain('tool.check')
+ expect(registeredEvents({ toolHints: true, agentTrim: true, deliveryScreen: true })).toEqual(
+ [...off, 'tool.describe', 'agent.offer', 'session.receive', 'session.send'].sort(),
+ )
+ })
+})
+
+describe('capabilityProbe option (ADR-451 item 5)', () => {
+ const BEAT = `${ROOT}/.claude-flow/mods/session.json`
+ let w: ReturnType<typeof world>
+ const boot = (on: Parameters<Parameters<typeof test>[2]>[1], version?: unknown) => {
+ w = world(on, {}, { [HELPER]: '' })
+ on('tool.check', () => ({ decision: 'allow' }))
+ if (version !== undefined) on('session.version', () => ({ value: version as never }))
+ }
+ const report = async ($: Parameters<Parameters<typeof test>[2]>[0]) => (await $.command.run(run('ruflo-mods'))).text ?? ''
+ const check = (command: string) => ({ tool: 'Bash', input: { command } }) as never
+
+ test('off by default: the report says off, nothing is added to the heartbeat', async ($, on) => {
+ boot(on, { version: '2.1.287', base: '2.1.287' })
+ await $.session.start(START)
+ expect(await report($)).toContain('probe: off (set the capabilityProbe option)')
+ const beat = w.files.get(BEAT) ?? ''
+ expect(beat).not.toContain('engine')
+ expect(beat).not.toContain('events')
+ })
+
+ test('on: version, fired count and the never-fired events are reported', { options: { capabilityProbe: true } }, async ($, on) => {
+ boot(on, { version: '2.1.287', base: '2.1.287' })
+ await $.session.start(START)
+ const line = (await report($)).split('\n').find(l => l.includes('probe: engine')) ?? ''
+ expect(line).toMatch(/probe: engine 2\.1\.287 · events fired \d+\/\d+ · never fired: /)
+ expect(Number(/fired (\d+)\//.exec(line)?.[1])).toBeGreaterThanOrEqual(2) // session.start and command.run fired
+ expect(line).not.toMatch(/never fired:.*\bsession\.start\b/)
+ expect(line).toMatch(/never fired:.*\btool\.check\b/)
+ const beat = JSON.parse(w.files.get(BEAT) ?? '')
+ expect(beat.engine).toBe('2.1.287')
+ expect(beat.events).toContain('tool.check')
+ })
+
+ test('on: an event that fires moves from never fired to fired', { options: { capabilityProbe: true } }, async ($, on) => {
+ boot(on, { version: '2.1.287', base: '2.1.287' })
+ await $.session.start(START)
+ const before = await report($)
+ await $.tool.check(check('ls')).catch(() => undefined)
+ const after = await report($)
+ expect(before).toMatch(/never fired:.*\btool\.check\b/)
+ expect(after).not.toMatch(/never fired:.*\btool\.check\b/)
+ })
+
+ test('on: a build that does not expose the version says so and still counts events', { options: { capabilityProbe: true } }, async ($, on) => {
+ boot(on)
+ on('session.version', () => ({ deny: 'not available' }))
+ await $.session.start(START)
+ expect(await report($)).toContain('probe: engine version not exposed · events fired')
+ expect(JSON.parse(w.files.get(BEAT) ?? '').engine).toBeNull()
+ })
+
+ test('on: hostile version text is not echoed, and the probe changes no verdict', { options: { capabilityProbe: true } }, async ($, on) => {
+ boot(on, { version: '2.1.287\n\u001b]0;pwned\u0007<script>', base: 7 })
+ await $.session.start(START)
+ const text = await report($)
+ expect(text).toContain('engine version not exposed')
+ expect(text).not.toContain('pwned')
+ // still refused by the guard (the probe never loosens) and a plain call is still allowed (never denies)
+ const bad = await $.tool.check(check(['rm', '-rf', '/'].join(' ')))
+ expect(bad.decision).toBe('deny')
+ expect((await $.tool.check(check('ls'))).decision).toBe('allow')
+ const odd = await $.command.run({ ...run('ruflo-mods'), args: '\u0000'.repeat(10) })
+ expect(odd.text).toContain('probe: engine')
+ })
+})