🌊 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
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.jsonindex 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.mdindex 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.tsindex 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: booleanreadonly agentTrimKeep: ReadonlySet<string>readonly deliveryScreen: boolean+ readonly capabilityProbe: booleanreadonly modTrust: TrustPolicyreadonly 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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, gustate.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.tsindex 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.shindex 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.tsnew file mode 100644index 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')+ })+})