Skip to content

Reflex v0.17.0: MCP and protected-file gate, reflex learn, plugin bundle

Choose a tag to compare

@ursuciprian ursuciprian released this 30 Sep 14:07
· 35 commits to main since this release
f3eb136

Reflex makes AI coding agents prod-safe for infra teams: a pre-execution hook for Claude Code, Codex CLI, opencode and pi that judges each shell command, MCP call and protected-file write by where it points and what it will change, then runs it, asks a human, or blocks it.

Install: /plugin marketplace add ursuciprian/reflex then /plugin install reflex@reflex · or npx @ursuciprian/reflex@0.17.0 setup (run outside a Reflex checkout) · GitHub Action: uses: ursuciprian/reflex@v0.17.0

Added

  • MCP server guardrails: the gate judges MCP tool calls before they run, in Claude Code and Codex (mcp__<server>__<tool>), opencode, pi and Hermes. Rules in setup/tool-gate/mcp.json ask on a destructive verb in the tool name (delete, destroy, drop, terminate, remove, purge, truncate, force, reset, rollback, uninstall and more), a scale to zero, a bucket policy, security group or IAM change, destructive SQL and an HTTP DELETE, and deny when an argument or the server points at production. A shell command in an argument goes through the shell rules. Read-like tools pass unlogged; an unknown tool is logged keyless, judged by Jev with a key, or asks with "mcp": {"unknown": "ask"}. The freeze, queue, runaway guard, trace, audit and webhook apply. A team policy can add mcp rules, stricter only.
  • Protected files: a write by Edit, Write, MultiEdit, NotebookEdit, apply_patch or the opencode, pi and Hermes file tools to .github/workflows/, .gitlab-ci.yml, production paths, production Terraform, tfvars and Dockerfiles, .reflex/, agent settings and hooks, .mcp.json, git hooks or shell startup files asks, with the path and why in the reason (setup/tool-gate/protected.json). config.json protected and a team policy protected list add globs.
  • npm run eval-mcp: 83 golden MCP and file-write cases (setup/tool-gate/golden-mcp.json), keyless or with Jev.
  • reflex learn: fast-lane entries from what you approved yourself, to reduce permission prompts
    over time. It reads only a human's answers (approval queue items approved or denied with reflex queue, Reflex asks and Claude Code permission dialogs that then ran, refusals, and asks left
    unanswered for 10 minutes), never a System 1 allow or a System 2 verdict. It reuses reflex suggest's templates and safety proof and proposes a shape only when it was approved --min times
    (default 3) in at least 2 sessions and never refused, and is not production or always-human.
    Destructive, prod, secret, tamper, freeze and MCP commands are never learned. It prints the humans
    per 100 commands before and after on your transcripts. --write asks on the terminal (or needs
    --yes) and records id, learned_at and learned_from per entry; --list, --forget <id> and
    --prune review and remove learned entries; --team prints a .reflex/policy.json fastlane
    snippet. reflex status notes how many approved shapes could stop asking; reflex doctor flags
    learned entries unused for 60 days. An agent running reflex learn --write, --forget or
    --prune gets a tamper ask. CLI only: the Claude Code plugin does not ship it. On the maintainer's
    history (32,001 commands, 30 days, keyless) it proposed nothing: 50.4 humans per 100 before and
    after, because the commands that ask there are interpreters, sed -i, curl, gh and git.
    A learned entry is pinned to the sha256 of the scripts it runs; an edited script stops passing.

Changed

  • gate.mjs split into modules; no behaviour change. config.mjs (settings, validation, redaction),
    shell.mjs (words, heredocs, rule spellings), scripts.mjs (local scripts), readonly.mjs
    (read-only detection, pipelines), rules.mjs (checkRules, the large-command deny rules),
    tamper.mjs, jev.mjs (context, key, provider call, cache, jevJudge) and selfcheck.mjs.
    gate.mjs keeps the CLI, precheck, decide and the hook adapters and re-exports every name that
    moved. The new modules are in the plugin bundle and on the tamper list like gate.mjs.

Security

  • User fast lane: a script body with inline interpreter code (node -e, python -c, sh -c,
    deno eval) no longer qualifies, and reflex and the gate's entry points are denied words.
  • Tamper: a local script (package.json script, Makefile recipe, shell file) that runs reflex setup,
    reflex queue approve|deny, reflex suggest --write or reflex learn --write is a tamper ask,
    also in the bundled fast lane (npm run lint). reflex suggest or reflex learn with its flags in
    a variable, "$@", xargs, eval or a function is a tamper ask too.
  • Tamper: more spellings of a shell write into the Reflex data directory (REFLEX_DATA_DIR, else
    $XDG_STATE_HOME/reflex or ~/.local/state/reflex) or the config directory are tamper asks: from
    a working directory inside or above it with no cd (echo x >> reflex/trace.jsonl from
    ~/.local/state, echo x >> ../feedback.jsonl from queue/), a relative cd reflex from the
    parent, a .. climb, a glob (refle?, [r]eflex), ./ or // in the path, another case, a
    symlinked spelling, an archive unpacked in the parent or cp/rsync into it (tar -xf, tar -C,
    cp -r x/. .), and a Reflex file under a variable the command does not set ($D/trace.jsonl,
    ${D}feedback.jsonl, cd $Q && tee q-1.json). $PWD and $TMPDIR are resolved. A local script
    is read the same way. A (cd /tmp) subshell no longer leaves the next command resolved to /tmp,
    and cd ~- is cd -. A custom data or config directory is matched only as itself or a path in
    it, not a sibling that starts with its name. Not caught: a bare variable (echo x >> $F), a
    generic file name such as config.json under a variable, or an unknown program run in the parent
    that writes reflex/ without naming it. reflex learn trusts these logs as far as this check
    protects them; the GUIDE says so.
  • Importing a Reflex file no longer does anything. install.mjs, eval.mjs, eval-ladder.mjs,
    eval-compare.mjs, eval-instructions.mjs, status.mjs, report.mjs, audit.mjs, replay.mjs,
    test.mjs, hook.mjs, scripts/reflex, scripts/reflex-review and scripts/build-plugin.mjs
    ran their work at the top level, so an import("./install.mjs") (a review agent reading the code)
    rewrote a real ~/.claude/settings.json. Every script now runs only when started directly
    (isMain in failsafe.mjs: the real path of import.meta.url against the real path of
    process.argv[1], so a symlinked reflex still runs). node install.mjs ..., reflex setup and
    npm run eval work as before. A test imports every *.mjs at the top, in adapters/,
    scripts/ and router/ in a child with HOME, CLAUDE_CONFIG_DIR, XDG_CONFIG_HOME,
    XDG_STATE_HOME and TMPDIR in an empty scratch directory, and fails when anything appears or
    changes there or a process is started.
  • Tamper: the files the tamper rule protects inside the checkout are read from the checkout instead
    of a hand-kept list, which had missed tools.mjs, freeze.mjs, notify.mjs, mcp.mjs,
    laya.mjs, learn.mjs, status.mjs, replay.mjs, suggest.mjs, audit.mjs,
    eval-compare.mjs, test.mjs and more. Covered now: every top-level *.mjs, *.js, *.sh and
    *.json file (install.sh, package.json, .mcp.json) and everything under setup/,
    scripts/, adapters/, hooks/, router/, routing/, plugin/, commands/, skills/,
    .claude-plugin/, .codex-plugin/ and .agents/. The gate's selfcheck fails when a file of the
    checkout is neither covered nor listed as not run by Reflex (docs, site, examples and the like).

Fixed

  • Hermes: the injection guard's post_tool_call matcher named MCP tools mcp__.*, but Hermes names them mcp_<server>_<tool>, so MCP results were never scanned there. It is mcp_.* now.
  • Plugin bundle: the stripped gate, run without --plugin and with no key source, no longer calls the Jev provider without a key; it asks. A test checks that no request is sent.
  • The npm package no longer ships .claude-plugin/marketplace.json, which points at plugin/ (installed from git, not npm).

Docs: https://ursuciprian.github.io/reflex/ · Full changelog: https://github.com/ursuciprian/reflex/blob/main/CHANGELOG.md