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): rureOffer — offer ruRE when the model reads a binary (ADR-498) (#4446)

rUvcac404c54c4f
diff --git a/plugins/ruflo-mods/.claude-plugin/plugin.json b/plugins/ruflo-mods/.claude-plugin/plugin.json
index 5e0574b233..1543ebd25c 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.6.2",
+ "version": "0.7.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
@@ -82,6 +82,13 @@
"required": false,
"default": false
},
+ "rureOffer": {
+ "type": "boolean",
+ "title": "Offer ruRE for binaries the model reads",
+ "description": "When the model reads or writes an executable, library, Electron .asar or CUDA file (.exe .dll .so .dylib .node .asar .cubin .fatbin .ptx .evm .bytecode) inside the project, add one line beneath that answer saying ruRE can look inside it without running it, and how. Offer only: it never runs ruRE, never denies or changes a tool call, and names at most three files a turn and twelve a session, each once. The line holds only validated project-relative paths and fixed words, never file contents. Does nothing when the session has no ruRE tool or the answer is a subagent's. Off by default.",
+ "required": false,
+ "default": false
+ },
"capabilityProbe": {
"type": "boolean",
"title": "Capability probe",
diff --git a/plugins/ruflo-mods/CHANGELOG.md b/plugins/ruflo-mods/CHANGELOG.md
index cea9265c54..0d1f107822 100644
--- a/plugins/ruflo-mods/CHANGELOG.md
+++ b/plugins/ruflo-mods/CHANGELOG.md
@@ -2,6 +2,9 @@
Newest first. One `## <version> — <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; older versions: `git log -- plugins/ruflo-mods`.
+## 0.7.0 — 2026-10-23
+- feat: option `rureOffer` (default off, ADR-498): when the model reads or writes a binary, library, `.asar` or CUDA file inside the project, one line beneath the answer says ruRE can look inside it without running it, and how (`/ruflo run dt-re-auto <path>`, or `rure_analyze_binary` / `rure_analyze_cuda`). Offer only: it never runs ruRE, never denies or edits a call, shows at most three files a turn and twelve a session once each, only validated project-relative paths, and nothing from the file. Inert without a ruRE tool and on subagent answers
+
## 0.6.2 — 2026-10-14
- fix: the mod's route context uses the same query-coverage scoring as hook-handler.cjs (inflection variants, IDF weights, coverage >= 0.15), so a short prompt finds a long memory entry and "migrations" finds "migration" (#4136, #4172); the ADR-404 parity test holds again
diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.md
index 0fc788fdeb..3fa2e34020 100644
--- a/plugins/ruflo-mods/README.md
+++ b/plugins/ruflo-mods/README.md
@@ -93,6 +93,7 @@ Claude Code reads a plugin's options from `pluginConfigs["ruflo-mods@ruflo"].opt
| `agentTrim` | `false` | Keep agent types the project does not use out of the agent listing. Measured saving about 4,000 tokens per request (4,236 on a 69-type catalogue, one model); a hidden type the prompt does not name is refused at dispatch, one the prompt names can still be dispatched. Evidence: [trim measurement](../../v3/docs/validation/ruflo-mods-trim-measure-2026-10.md) |
| `agentTrimKeep` | empty | Comma-separated agent type names `agentTrim` must keep offered. Evidence: [live validation](../../v3/docs/validation/ruflo-mods-live-2026-10.md) |
| `deliveryScreen` | `false` | ADR-451 screen: drops peer, relay or webhook deliveries that carry injection phrasing and refuses outgoing messages that carry a secret shape; never screens your own Remote Control prompts; names the rule, never the text. Caught 76% of its own 50-injection test set before the rules were tuned on it (figure from the PR #3741 description, not a repo doc); the real-world rate is unknown. No live evidence doc yet; design in [ADR-451](../../v3/docs/adr/ADR-451-mod-capability-roadmap.md) item 3 |
+| `rureOffer` | `false` | `tool.call` + `turn.complete` (ADR-498): when the model reads or writes an executable, library, `.asar` or CUDA file in the project, adds one line beneath that answer saying ruRE can inspect it without running it, and how. Offer only: never runs ruRE, never denies or edits a call; at most 3 files a turn, 12 a session, each once; validated project-relative paths only; inert without a ruRE tool and on subagent answers. Design in [ADR-498](../../v3/docs/adr/ADR-498-mods-rure-offer.md) |
| `compactCarry` | `false` | `session.compact` (ADR-451 item 7): appends at most 600 characters to what the compaction summary keeps: swarm id, topology word, agent count, open claim ids and status, last route agent, budget and policy words. Fixed words and identifiers only, screened, fails open, skipped when no swarm or claim is open. No live evidence doc yet; design in [ADR-451](../../v3/docs/adr/ADR-451-mod-capability-roadmap.md) |
| `capabilityProbe` | `false` | Observability only (ADR-451 item 5): `/ruflo-mods` gains `probe: engine <version> · events fired n/m · never fired: ...`; reads no payload and never denies, rewrites or delays. Live run: [ruflo-mods-options-live-2026-10.md](../../v3/docs/validation/ruflo-mods-options-live-2026-10.md); design in [ADR-451](../../v3/docs/adr/ADR-451-mod-capability-roadmap.md) |
| `sessionRollup` | `false` | Observability only (ADR-451 item 6): at session end one counter record (no prompt text, inputs or paths) goes to a user-global ledger capped at 50 sessions and 32 KB; `/ruflo-mods` shows the last few. Live run: [ruflo-mods-options-live-2026-10.md](../../v3/docs/validation/ruflo-mods-options-live-2026-10.md); design in [ADR-451](../../v3/docs/adr/ADR-451-mod-capability-roadmap.md) |
diff --git a/plugins/ruflo-mods/hooks/options.ts b/plugins/ruflo-mods/hooks/options.ts
index 17c06a3294..0a94781723 100644
--- a/plugins/ruflo-mods/hooks/options.ts
+++ b/plugins/ruflo-mods/hooks/options.ts
@@ -16,6 +16,7 @@ export type ModOptions = {
readonly agentTrimKeep: ReadonlySet<string>
readonly deliveryScreen: boolean
readonly compactCarry: boolean
+ readonly rureOffer: boolean
readonly capabilityProbe: boolean
readonly sessionRollup: boolean
readonly sessionAttention: boolean
@@ -50,6 +51,7 @@ export function readOptions(options: PluginOptions | undefined): ModOptions {
agentTrimKeep: keepNames(o.agentTrimKeep),
deliveryScreen: bool(o.deliveryScreen, false),
compactCarry: bool(o.compactCarry, false),
+ rureOffer: bool(o.rureOffer, false),
capabilityProbe: bool(o.capabilityProbe, false),
sessionRollup: bool(o.sessionRollup, false),
sessionAttention: bool(o.sessionAttention, false),
diff --git a/plugins/ruflo-mods/hooks/register.ts b/plugins/ruflo-mods/hooks/register.ts
index 646a766a9d..53f428b4c1 100644
--- a/plugins/ruflo-mods/hooks/register.ts
+++ b/plugins/ruflo-mods/hooks/register.ts
@@ -12,6 +12,7 @@ import { registerNoun } from './noun'
import { readOptions } from './options'
import { registerProbe } from './probe'
import { registerRollup } from './rollup'
+import { registerRureOffer } from './rure-offer'
import { registerRoute } from './route'
import { registerSession } from './session'
import { createState } from './state'
@@ -48,4 +49,5 @@ export const register: Register = (on, options) => {
if (opts.agentTrim) registerAgents(on, state, opts)
if (opts.deliveryScreen) registerDelivery(on, state)
if (opts.compactCarry) registerCompact(on, state)
+ if (opts.rureOffer) registerRureOffer(on, state)
}
diff --git a/plugins/ruflo-mods/hooks/rure-offer/index.ts b/plugins/ruflo-mods/hooks/rure-offer/index.ts
new file mode 100644
index 0000000000..f27c97ecff
--- /dev/null
+++ b/plugins/ruflo-mods/hooks/rure-offer/index.ts
@@ -0,0 +1,79 @@
+import type { On } from 'claude-code'
+
+import { under, type ModState } from '../state'
+import { candidate, MAX_BYTES, MAX_PENDING, MAX_PER_SESSION, MAX_PER_TURN, OFFER_TOOLS, offerLine } from './paths'
+
+/** A ruRE tool the session can call: `mcp__<server>__rure_analyze_binary`, the one every ruRE install carries. */
+const RURE_TOOL = /__rure_analyze_binary$/
+
+/**
+ * The ruRE offer (ADR-498). Off unless the `rureOffer` option is on. When the model reads or writes a file ruRE can look inside (an
+ * executable, a library, an Electron `.asar`, a CUDA `.cubin`), it adds ONE line beneath that turn's answer naming up to three such files
+ * and how to inspect them without running them. It never runs ruRE, never denies or changes a tool call, never touches the transcript,
+ * and is inert where the session has no ruRE tool or the answer is a subagent's.
+ *
+ * `tool.call` only records a path; `turn.complete` checks it is still a plain file of a size ruRE accepts, then says it once.
+ */
+export function registerRureOffer(on: On, state: ModState) {
+ const offer = state.rureOffer
+
+ offer.enabled = true
+
+ on('session.start', async ($, e, next) => {
+ const result = await next(e)
+
+ try {
+ offer.available = (await $.tool.list()).some(tool => tool.mcp && RURE_TOOL.test(tool.name))
+ } catch {
+ offer.available = false
+ }
+
+ return result
+ })
+
+ on('tool.call', async ($, e, next) => {
+ const result = await next(e)
+
+ if (!offer.available || (result as { deny?: unknown } | undefined)?.deny !== undefined || !OFFER_TOOLS.has(e.tool)) return result
+
+ const path = candidate(state.root, (e as { file_path?: unknown }).file_path)
+
+ if (path !== null && !offer.offered.has(path) && !offer.pending.includes(path) && offer.pending.length < MAX_PENDING) offer.pending.push(path)
+
+ return result
+ })
+
+ on('turn.complete', async ($, e, next) => {
+ const result = await next(e)
+
+ // Only the main loop's answer carries the line: a subagent's answer goes back to the model that asked for it.
+ if (e.agentId !== undefined || offer.pending.length === 0) return result
+ if (e.isAborted) {
+ offer.pending.length = 0
+
+ return result
+ }
+
+ const waiting = offer.pending.splice(0)
+ const shown: string[] = []
+
+ for (const path of waiting) {
+ if (shown.length >= MAX_PER_TURN || offer.shown + shown.length >= MAX_PER_SESSION) break
+
+ try {
+ const stat = await $.fs.stat(under(state, path))
+
+ if (stat.kind === 'file' && stat.isLink !== true && stat.size > 0 && stat.size <= MAX_BYTES) shown.push(path)
+ } catch {
+ // gone, or not readable: nothing to offer
+ }
+ }
+
+ if (shown.length === 0 || typeof result?.text !== 'string') return result
+
+ for (const path of shown) offer.offered.add(path)
+ offer.shown += shown.length
+
+ return { ...result, text: `${result.text}\n\n${offerLine(shown)}` }
+ })
+}
diff --git a/plugins/ruflo-mods/hooks/rure-offer/paths.ts b/plugins/ruflo-mods/hooks/rure-offer/paths.ts
new file mode 100644
index 0000000000..f5c9f65847
--- /dev/null
+++ b/plugins/ruflo-mods/hooks/rure-offer/paths.ts
@@ -0,0 +1,48 @@
+/**
+ * The ruRE offer's pure parts (ADR-498): which file a tool call touched is worth offering ruRE for, and the one line that offers it.
+ * Pure: strings in, strings out, no engine call. The rules mirror the console's `sample` field (relative, plain characters, no `..`) so
+ * everything offered can actually be run from the console; nothing outside the project, or with an odd name, is ever named.
+ */
+
+/** Tools whose call names a file by `file_path`: the model reading or writing the file. */
+export const OFFER_TOOLS: ReadonlySet<string> = new Set(['Read', 'Write', 'Edit', 'MultiEdit'])
+
+/** What ruRE can read by extension (`.hex` and `.bin` are left out: too often firmware or plain data). `libx.so.1` counts as a `.so`. */
+const RURE_FILE = /\.(?:exe|dll|so(?:\.\d{1,3}){0,3}|dylib|node|asar|cubin|fatbin|ptx|evm|bytecode)$/i
+/** The console's `sample` rule: plain characters only, at most 160. */
+const PLAIN = /^[A-Za-z0-9._/-]{1,160}$/
+
+export const MAX_PENDING = 8
+export const MAX_PER_TURN = 3
+export const MAX_PER_SESSION = 12
+/** ruRE refuses larger files (128 MiB), so offering one would be an offer that fails. */
+export const MAX_BYTES = 128 * 1024 * 1024
+
+/**
+ * The project-relative path a tool call's `file_path` means, when ruRE can read that kind of file and the console would accept the path;
+ * otherwise null. An absolute path counts only under `root`. Nothing with `..`, an empty segment, a leading `-` or other characters is named.
+ */
+export function candidate(root: string, filePath: unknown): string | null {
+ if (typeof filePath !== 'string' || filePath.length === 0 || filePath.length > 400) return null
+
+ const base = root.replace(/\/+$/, '')
+ const relative = filePath.startsWith('/') ? (base !== '' && filePath.startsWith(`${base}/`) ? filePath.slice(base.length + 1) : null) : filePath.replace(/^\.\//, '')
+
+ if (relative === null || !PLAIN.test(relative) || relative.startsWith('-') || !RURE_FILE.test(relative)) return null
+ if (relative.split('/').some(part => part === '' || part === '.' || part === '..')) return null
+
+ return relative
+}
+
+/** `a.dll`, `a.dll and b.so`, `a.dll, b.so and c.exe`. */
+const names = (paths: readonly string[]): string => (paths.length === 1 ? (paths[0] as string) : `${paths.slice(0, -1).join(', ')} and ${paths[paths.length - 1]}`)
+
+/**
+ * The one line shown beneath the answer. Static words around plain, already-validated paths: nothing the file contains reaches it, and it
+ * says plainly that ruRE only parses.
+ */
+export function offerLine(paths: readonly string[]): string {
+ const them = paths.length === 1 ? 'it' : 'them'
+
+ return `ruRE can look inside ${names(paths)} without running ${them}: in the ruflo console run /ruflo run dt-re-auto ${paths[0]}, or ask me to call rure_analyze_binary (rure_analyze_cuda for GPU code). It only parses; nothing is executed.`
+}
diff --git a/plugins/ruflo-mods/hooks/state.ts b/plugins/ruflo-mods/hooks/state.ts
index 5ea0d2efc7..f08b261564 100644
--- a/plugins/ruflo-mods/hooks/state.ts
+++ b/plugins/ruflo-mods/hooks/state.ts
@@ -39,6 +39,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 }
+ /** The ruRE offer (ADR-498): whether it is on, whether the session has a ruRE tool, files waiting for the turn's end, files already offered, and how many were. */
+ rureOffer: { enabled: boolean; available: boolean; pending: string[]; offered: Set<string>; shown: number }
/** `session.compact` carry (ADR-451 item 7): whether it is on and how many compactions carried a block. */
compact: { enabled: boolean; carried: number }
/** Capability probe (ADR-451 item 5): engine version and which registered events fired. */
@@ -75,6 +77,7 @@ export function createState(): ModState {
agentTrim: { enabled: false, hidden: new Set(), prompt: '' },
delivery: { enabled: false, consumed: 0, blocked: 0 },
compact: { enabled: false, carried: 0 },
+ rureOffer: { enabled: false, available: false, pending: [], offered: new Set(), shown: 0 },
probe: probeState(),
grounding: groundingState(),
rollup: rollupState(),
diff --git a/plugins/ruflo-mods/scripts/smoke.sh b/plugins/ruflo-mods/scripts/smoke.sh
index d35d14dbbd..d78bc8b6d5 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.6.2 (ADR-404, ADR-447).
+# Structural + security smoke for ruflo-mods v0.7.0 (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.6.2"
+step "1. plugin.json declares ruflo-mods 0.7.0"
grep -q '"name": "ruflo-mods"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.6.2"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.7.0"' "$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" \
diff --git a/v3/@claude-flow/cli/__tests__/mods/harness.ts b/v3/@claude-flow/cli/__tests__/mods/harness.ts
index a62913d907..bb8b79aa7a 100644
--- a/v3/@claude-flow/cli/__tests__/mods/harness.ts
+++ b/v3/@claude-flow/cli/__tests__/mods/harness.ts
@@ -13,7 +13,7 @@
* absent (what is beneath answers); in a `.catch`, `next` is replay-safe
* (`next.called`, `next.error`) and its answer stands;
* - `e` is frozen; matchers narrow on equal values, arrays (any of) and RegExps;
- * - `$` ops: fs.stat rejects ENOENT for a missing path, fs.read rejects
+ * - `$` ops: tool.list (from `world.tools`), fs.stat rejects ENOENT for a missing path, fs.read rejects
* over 4 MiB, env.get/set, settings.read, session.root, ui.*, command.register.
* What it does not model: tiers above the mod (sec-default is reasoned about,
* not run), budgets, streaming events, rendering.
@@ -41,6 +41,8 @@ export interface World {
failRead?: (path: string) => Error | undefined;
failStat?: (path: string) => Error | undefined;
failLog?: boolean;
+ /** What `$.tool.list()` returns (default: none). `mcp` marks an MCP server's tool. */
+ tools?: { name: string; description: string; mcp: boolean }[];
}
export function memoryWorld(root = '/work', settings: unknown = {}): World {
@@ -107,6 +109,11 @@ function engineOf(world: World) {
return typeof world.settings === 'function' ? (world.settings as () => unknown)() : world.settings;
},
},
+ tool: {
+ async list() {
+ return world.tools ?? [];
+ },
+ },
session: {
async root() {
return world.root;
diff --git a/v3/@claude-flow/cli/__tests__/mods/mods-rure-offer.test.ts b/v3/@claude-flow/cli/__tests__/mods/mods-rure-offer.test.ts
new file mode 100644
index 0000000000..6fb9b93784
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/mods/mods-rure-offer.test.ts
@@ -0,0 +1,135 @@
+/**
+ * ADR-498 — the ruRE offer: one line beneath an answer when the model touched a file ruRE can read.
+ * Off by default; offer-only (never runs ruRE, never denies, never edits a call); main loop only.
+ */
+import { describe, it, expect } from 'vitest';
+
+import { register } from '../../../../../plugins/ruflo-mods/hooks/register';
+import { candidate, offerLine } from '../../../../../plugins/ruflo-mods/hooks/rure-offer/paths';
+import { loadMod, memoryWorld, type World } from './harness';
+
+const RURE = { name: 'mcp__ruflo__rure_analyze_binary', description: 'Use when ...', mcp: true };
+const mem = (w: World) => w.files as Map<string, { text: string; mtimeMs: number }>;
+const file = (w: World, path: string, text = 'MZ-bytes') => mem(w).set(`/work/${path}`, { text, mtimeMs: 1 });
+
+async function start(world: World, options: Record<string, unknown> = { rureOffer: true }) {
+ const mod = loadMod(register, world, options);
+ await mod.dispatch('session.start', { cwd: world.root, surface: null, isInteractive: false }, (e) => ({ cwd: e.cwd }));
+ return mod;
+}
+type Mod = Awaited<ReturnType<typeof start>>
+const touch = (mod: Mod, path: string, tool = 'Read', extra: object = {}) =>
+ mod.dispatch('tool.call', { tool, tool_use_id: `t-${path}`, file_path: path, ...extra }, () => ({ result: 'ok' }));
+const end = (mod: Mod, extra: object = {}) =>
+ mod.dispatch('turn.complete', { answer: 'done', durationMs: 5, isAborted: false, turnId: 'u1', ...extra }, () => ({ text: 'done' }));
+
+describe('ADR-498 candidate paths (pure)', () => {
+ it('accepts project-relative files ruRE reads, and absolute ones only under the root', () => {
+ expect(candidate('/work', 'bin/app.exe')).toBe('bin/app.exe');
+ expect(candidate('/work', './lib/libx.so.1')).toBe('lib/libx.so.1');
+ expect(candidate('/work', '/work/k/a.cubin')).toBe('k/a.cubin');
+ expect(candidate('/work/', '/work/app.asar')).toBe('app.asar');
+ });
+
+ it('refuses everything else: other kinds, outside the root, traversal, odd characters, flags', () => {
+ for (const bad of ['a.txt', 'a.ts', 'a.hex', '/etc/x.so', '/workshop/a.dll', '../a.dll', 'a/../b.dll', 'a//b.dll', '-rf.dll', 'a b.dll', 'a;b.dll', 'a\n.dll', '$(x).dll', `${'a'.repeat(200)}.dll`]) {
+ expect(candidate('/work', bad), bad).toBeNull();
+ }
+ for (const bad of [undefined, null, 5, {}, '']) expect(candidate('/work', bad)).toBeNull();
+ });
+
+ it('the line names only the validated paths, with static words around them', () => {
+ expect(offerLine(['a.dll'])).toContain('inside a.dll without running it');
+ expect(offerLine(['a.dll', 'b.so'])).toContain('inside a.dll and b.so without running them');
+ expect(offerLine(['a.dll', 'b.so', 'c.exe'])).toContain('a.dll, b.so and c.exe');
+ expect(offerLine(['a.dll'])).toContain('It only parses; nothing is executed.');
+ });
+});
+
+describe('ADR-498 offer at turn end', () => {
+ it('is off unless the option is on', async () => {
+ const world = memoryWorld();
+ world.tools = [RURE];
+ file(world, 'a.exe');
+ const mod = await start(world, {});
+ await touch(mod, 'a.exe');
+ expect((await end(mod)).text).toBe('done');
+ });
+
+ it('offers once, beneath the answer, for a binary the model read', async () => {
+ const world = memoryWorld();
+ world.tools = [RURE];
+ file(world, 'a.exe');
+ const mod = await start(world);
+ await touch(mod, 'a.exe');
+ const out = await end(mod);
+ expect(out.text).toMatch(/^done\n\nruRE can look inside a\.exe without running it/);
+ // the same file is never offered twice, and nothing is pending for the next turn
+ await touch(mod, 'a.exe');
+ expect((await end(mod)).text).toBe('done');
+ });
+
+ it('is inert where the session has no ruRE tool (or only a non-MCP lookalike)', async () => {
+ for (const tools of [[], [{ name: 'rure_analyze_binary', description: '', mcp: false }]]) {
+ const world = memoryWorld();
+ world.tools = tools;
+ file(world, 'a.exe');
+ const mod = await start(world);
+ await touch(mod, 'a.exe');
+ expect((await end(mod)).text).toBe('done');
+ }
+ });
+
+ it('ignores other tools, other files, denied calls, empty and missing files', async () => {
+ const world = memoryWorld();
+ world.tools = [RURE];
+ file(world, 'a.exe');
+ file(world, 'empty.exe', '');
+ file(world, 'notes.txt');
+ const mod = await start(world);
+ await touch(mod, 'a.exe', 'Bash');
+ await touch(mod, 'notes.txt');
+ await touch(mod, 'empty.exe');
+ await touch(mod, 'missing.dll');
+ await mod.dispatch('tool.call', { tool: 'Read', tool_use_id: 'd', file_path: 'a.exe' }, () => ({ deny: 'no' }));
+ expect((await end(mod)).text).toBe('done');
+ });
+
+ it('a subagent’s answer and an aborted turn carry no line, and the pending file is not kept for later', async () => {
+ const world = memoryWorld();
+ world.tools = [RURE];
+ file(world, 'a.exe');
+ const mod = await start(world);
+ await touch(mod, 'a.exe');
+ expect((await end(mod, { agentId: 'sub-1' })).text).toBe('done');
+ expect((await end(mod, { isAborted: true })).text).toBe('done');
+ expect((await end(mod)).text).toBe('done'); // aborted turn dropped it
+ });
+
+ it('caps one line at three files, and the session at twelve', async () => {
+ const world = memoryWorld();
+ world.tools = [RURE];
+ const names = Array.from({ length: 30 }, (_, i) => `f${i}.dll`);
+ for (const n of names) file(world, n);
+ const mod = await start(world);
+ const listed = (text: string) => (/inside (.*?) without running/.exec(text)?.[1] ?? '').split(/, | and /).filter(Boolean);
+
+ for (const n of names.slice(0, 6)) await touch(mod, n);
+ expect(listed((await end(mod)).text as string)).toEqual(['f0.dll', 'f1.dll', 'f2.dll']);
+
+ let total = 3;
+ for (let i = 6; i < 30; i += 3) {
+ for (const n of names.slice(i, i + 3)) await touch(mod, n);
+ total += listed((await end(mod)).text as string).length;
+ }
+ expect(total).toBe(12);
+ });
+
+ it('never changes a tool call or its result', async () => {
+ const world = memoryWorld();
+ world.tools = [RURE];
+ file(world, 'a.exe');
+ const mod = await start(world);
+ expect(await touch(mod, 'a.exe')).toEqual({ result: 'ok' });
+ });
+});
diff --git a/v3/docs/adr/ADR-498-mods-rure-offer.md b/v3/docs/adr/ADR-498-mods-rure-offer.md
new file mode 100644
index 0000000000..6f7b693a45
--- /dev/null
+++ b/v3/docs/adr/ADR-498-mods-rure-offer.md
@@ -0,0 +1,36 @@
+# ADR 498: a mod that offers ruRE when the model reads a binary
+
+Status: Accepted (built and tested against the mod harness; ships in ruflo-mods 0.7.0, option off by default)
+
+Date: 2026-10-23
+
+Builds on: ADR-404 (ruflo as a Claude Code mod), ADR-494 to ADR-497 (the ruRE page and readers). The tools it points at are ruflo-rure ADR-0001 to ADR-0006.
+
+## 1. Context
+
+ruRE reads a program without running it, but nothing tells a person or the model that it is there at the moment a binary comes up. A model asked about `app.exe` tends to run `strings` or `file` through Bash, or guess. The console has a ruRE page; a session without the console, or a model mid-task, has no pointer.
+
+## 2. Decision
+
+An opt-in option, `rureOffer` (default off), registers three hooks:
+
+- **`session.start`** asks `$.tool.list()` once whether an MCP tool named `…__rure_analyze_binary` exists. If not, the mod does nothing for the session.
+- **`tool.call`** (observe only, after `next`): for `Read`, `Write`, `Edit` and `MultiEdit`, take `file_path`; if it is a project-relative path of plain characters (`A-Za-z0-9._/-`, at most 160, no `..`, no empty segment, no leading `-`) ending in `.exe .dll .so(.N) .dylib .node .asar .cubin .fatbin .ptx .evm .bytecode`, queue it (at most 8 waiting). An absolute path counts only under the session root. A denied call queues nothing. The call and its result are never changed.
+- **`turn.complete`**, main loop only (`agentId` absent), not aborted: stat each queued path through `$.fs`, keep only regular, non-link files of 1 byte to 128 MiB (what ruRE accepts), and append one line to the answer's `text` naming at most three of them. A path is offered once per session; twelve per session in all. An aborted turn drops its queue; a subagent's turn leaves it for the main loop's.
+
+The line is fixed words around already-validated paths: `ruRE can look inside <paths> without running <it|them>: in the ruflo console run /ruflo run dt-re-auto <first>, or ask me to call rure_analyze_binary (rure_analyze_cuda for GPU code). It only parses; nothing is executed.` Nothing the file contains reaches it.
+
+## 3. Why offer-only
+
+A mod that ran ruRE on every read would spend time and tokens on files the model only opened, and would put file-derived text under the answer. An offer costs one line, carries no file content, and leaves the choice to the person or the model. This also keeps the mod tighten-only in spirit: it cannot make any call do more.
+
+## 4. Limits, stated plainly
+
+- The extension list is a heuristic: a binary with another name, or a `.dll` that is plain text, is offered or missed accordingly. `.bin` and `.hex` are left out as too often plain data.
+- It sees only what the model's file tools name. A binary reached through Bash is not offered.
+- The line is shown beneath the answer by the engine's `turn.complete` text; a front-end that does not show that text shows nothing, and nothing breaks.
+- The folder-outside-the-project case is not offered; ruRE's console refuses it too (a separate decision, a person-only setting).
+
+## 5. Verification
+
+`v3/@claude-flow/cli/__tests__/mods/mods-rure-offer.test.ts` (10): the path rule for accepted and refused names (traversal, spaces, shell characters, flags, long names, outside the root), the line's wording, off by default, one offer then none, inert without an MCP ruRE tool, ignoring other tools, files, denied calls, empty and missing files, no line on a subagent's or an aborted turn, the 3-per-turn and 12-per-session caps, and the call's result unchanged. The harness gained `World.tools` and `$.tool.list`.