Ruflo
Ruflo retrieval and hook safety: activation, flagging and actual enforcement
Follow the retrieval guard’s feature gate, strict mode and string-length check, and distinguish best-effort hook telemetry from enforceable permission boundaries.
What you will learn
- Check the caller, not only the guard class
- Flagging and dropping are different policies
- Do not mistake best-effort hooks for a security gate
Before you start
- Basic Node.js, Git and command-line knowledge
- An owned repository and an explicit task/permission boundary
Explain the chapter’s implementation and reproduce its bounded check without mistaking a helper for a complete runtime.
Key takeaways
- The inspected backend gate still requires an exact enabled flag.
- Flag-only retention is not strict blocking, and string length is not UTF-8 bytes.
- Successful best-effort hooks do not certify persistence or authorization.
Check the caller, not only the guard class
AgentDbRetrievalGuard can flag unsafe or oversized results and optionally remove them. The inspected AgentDBBackend search path calls applyRetrievalGuard after HNSW or brute-force retrieval. That caller returns unchanged results unless the guard exists, the enabled flag is exactly the string true and the result set is nonempty. Supplying an explicit guard configuration does not bypass that caller’s flag check.
This matters because a nearby comment suggests an explicit configuration can scan without the flag, while the executable condition still requires it. Our isolated gate probe used a fake receiver and confirmed both branches. It did not construct a database, verify every query path or run a real prompt-injection detector. Treat source comments as explanations to check against execution.
Flagging and dropping are different policies
Default filtering retains suspicious entries with annotations; strict blockOnSuspicion removes them. Oversized content is not scanned in that branch. The setting is named maxPayloadBytes, but the string check uses JavaScript content.length, which counts UTF-16 code units, not UTF-8 bytes. Five Han characters have length five and occupy fifteen UTF-8 bytes; at a limit of eight the size branch does not flag them.
The content scanner in our probe was an injected fake, so this demonstrates wrapper policy and size accounting, not detection effectiveness. The separate safeJsonParse helper removes __proto__, constructor and prototype keys recursively during JSON parsing. That targeted defense does not authenticate memory authors, authorize transfers or make retrieved prose trustworthy instructions.
Do not mistake best-effort hooks for a security gate
The core hook shim treats many operations as best-effort telemetry: it suppresses child output, uses bounded synchronous calls and exits successfully rather than blocking a turn when the CLI fails. Its pre-tool branch also adapts output to the detected host. A zero exit status here is not proof that learning persisted or that the requested tool action passed a security review.
Enforce permitted tools, data access and external writes independently in the actual host. Check which memory backend and retrieval path are active, whether strict behavior is wanted, and whether tests cover multilingual payloads and failed hooks. This is an implementation review with narrow probes, not a penetration test or a certification of a deployed Ruflo installation.
Implementation steps
- 1
Identify the active backend and actual retrieval call path.
- 2
Test flag-off, flag-on and strict policies independently.
- 3
Include multibyte content and failed-hook cases.
- 4
Enforce host permissions outside advisory hook text.
Copy-ready example
{"guardEnabledValue":"true","strictModeIsSeparate":true,"sizeCheckUnit":"UTF-16 code units","realSecurityScannerExecuted":false,"hookExitZeroMeansPolicyApproved":false,"deployedSecurityVerified":false}Frequently asked questions
Does constructing a configured guard force every backend search to scan?
Not in the inspected caller: applyRetrievalGuard also requires the exact enabled environment flag. Other paths must be checked separately.
Does a hook returning zero prove the learning step succeeded?
No. The core shim intentionally uses best-effort behavior and can suppress a failed child invocation.
Sources
- plugins/ruflo-core/hooks/hooks.jsonSource checked 2026-09-08
- plugins/ruflo-core/scripts/ruflo-hook.cjsSource checked 2026-09-08
- v3/@claude-flow/memory/src/agentdb-retrieval-guard.tsSource checked 2026-09-08
- v3/@claude-flow/memory/src/agentdb-backend.tsSource checked 2026-09-08
- v3/@claude-flow/memory/src/json-security.tsSource checked 2026-09-08